From 61ec50dabe14c5d4582ac187706ea27645b3562b Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Wed, 29 Nov 2017 10:54:33 -0500 Subject: [PATCH] Change Doxygen comment style from //! to /// Also see https://groups.google.com/forum/#!topic/cryptopp-users/A7-Xt5Knlzw --- 3way.h | 32 +- adler32.h | 8 +- aes.h | 22 +- algebra.h | 318 ++--- algparam.h | 224 ++-- arc4.h | 36 +- argnames.h | 160 +-- aria.h | 46 +- asn.h | 330 ++--- authenc.h | 58 +- base32.h | 198 +-- base64.h | 198 +-- basecode.h | 92 +- blake2.h | 198 +-- blowfish.h | 20 +- blumshub.h | 10 +- camellia.h | 14 +- cast.h | 44 +- cbcmac.h | 10 +- ccm.h | 46 +- chacha.h | 62 +- channels.h | 10 +- cmac.h | 30 +- config.h | 22 +- cpu.h | 426 +++--- crc.h | 16 +- cryptlib.cpp | 32 +- cryptlib.h | 3562 +++++++++++++++++++++++++------------------------- default.h | 276 ++-- des.h | 82 +- dh.h | 286 ++-- dh2.h | 22 +- dll.h | 6 +- dmac.h | 30 +- drbg.h | 332 ++--- dsa.h | 38 +- eax.h | 40 +- ec2n.h | 44 +- eccrypto.h | 438 +++---- ecp.h | 52 +- ecpoint.h | 134 +- elgamal.h | 30 +- emsa2.h | 8 +- eprecomp.h | 4 +- esign.h | 72 +- factory.h | 92 +- fhmqv.h | 46 +- files.h | 118 +- filters.h | 1098 ++++++++-------- fips140.h | 106 +- gcm.h | 54 +- gf256.h | 6 +- gf2_32.h | 6 +- gf2n.h | 216 +-- gfpcrypt.h | 382 +++--- gost.h | 26 +- gzip.h | 106 +- hex.h | 28 +- hkdf.h | 22 +- hmac.h | 32 +- hmqv.h | 42 +- hrtimer.h | 16 +- ida.h | 58 +- idea.h | 18 +- integer.h | 878 ++++++------- iterhash.h | 136 +- kalyna.h | 118 +- keccak.h | 96 +- lubyrack.h | 12 +- luc.h | 130 +- mars.h | 14 +- md4.h | 2 +- md5.h | 8 +- mdc.h | 22 +- mersenne.h | 128 +- misc.h | 1762 ++++++++++++------------- modarith.h | 302 ++--- modes.h | 204 +-- mqueue.h | 4 +- mqv.h | 144 +- nbtheory.h | 154 +-- network.h | 30 +- oaep.h | 6 +- oids.h | 16 +- osrng.h | 188 +-- ossig.h | 96 +- padlkrng.h | 132 +- panama.h | 32 +- pch.h | 4 +- pkcspad.h | 26 +- poly1305.h | 190 +-- polynomi.h | 178 +-- ppc-crypto.h | 426 +++--- pssr.h | 48 +- pubkey.h | 1126 ++++++++-------- pwdbased.h | 54 +- queue.h | 36 +- rabin.h | 64 +- randpool.h | 90 +- rc2.h | 44 +- rc5.h | 18 +- rc6.h | 14 +- rdrand.h | 98 +- rijndael.h | 58 +- ripemd.h | 40 +- rng.h | 82 +- rsa.h | 182 +-- rw.h | 64 +- safer.h | 52 +- salsa.cpp | 2 - salsa.h | 36 +- seal.h | 24 +- secblock.h | 732 +++++------ seckey.h | 604 ++++----- seed.h | 20 +- serpent.h | 12 +- sha.h | 258 ++-- sha3.h | 68 +- shacal2.h | 30 +- shark.h | 24 +- simon.cpp | 92 +- simon.h | 126 +- simple.h | 266 ++-- siphash.h | 118 +- skipjack.h | 26 +- sm3.h | 64 +- sm4.h | 54 +- smartptr.h | 82 +- socketft.h | 18 +- sosemanuk.h | 34 +- speck.cpp | 88 +- speck.h | 126 +- square.h | 14 +- strciphr.h | 552 ++++---- tea.h | 72 +- threefish.h | 128 +- trap.h | 144 +- trdlocal.h | 4 +- trunhash.h | 2 +- ttmac.h | 18 +- twofish.h | 12 +- vmac.h | 34 +- wait.h | 6 +- wake.h | 28 +- whrlpool.h | 2 +- winpipes.h | 12 +- xtr.h | 16 +- xtrcrypt.h | 2 +- zdeflate.h | 94 +- zinflate.h | 30 +- zlib.h | 8 +- 151 files changed, 11089 insertions(+), 11091 deletions(-) diff --git a/3way.h b/3way.h index 9dba3c59..19d2ff63 100644 --- a/3way.h +++ b/3way.h @@ -1,7 +1,7 @@ // 3way.h - originally written and placed in the public domain by Wei Dai -//! \file 3way.h -//! \brief Classes for the 3-Way block cipher +/// \file 3way.h +/// \brief Classes for the 3-Way block cipher #ifndef CRYPTOPP_THREEWAY_H #define CRYPTOPP_THREEWAY_H @@ -12,21 +12,21 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ThreeWay_Info -//! \brief ThreeWay block cipher information +/// \class ThreeWay_Info +/// \brief ThreeWay block cipher information struct ThreeWay_Info : public FixedBlockSize<12>, public FixedKeyLength<12>, public VariableRounds<11> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "3-Way";} }; -//! \class ThreeWay -//! \brief ThreeWay block cipher -//! \sa 3-Way +/// \class ThreeWay +/// \brief ThreeWay block cipher +/// \sa 3-Way class ThreeWay : public ThreeWay_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief Class specific implementation and overrides used to operate the cipher. - //! \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions + /// \class Base + /// \brief Class specific implementation and overrides used to operate the cipher. + /// \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -37,18 +37,18 @@ class ThreeWay : public ThreeWay_Info, public BlockCipherDocumentation FixedSizeSecBlock m_k; }; - //! \class Enc - //! \brief Class specific methods used to operate the cipher in the forward direction. - //! \details Implementations and overrides in \p Enc apply to \p ENCRYPTION. + /// \class Enc + /// \brief Class specific methods used to operate the cipher in the forward direction. + /// \details Implementations and overrides in \p Enc apply to \p ENCRYPTION. class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \class Dec - //! \brief Class specific methods used to operate the cipher in the reverse direction. - //! \details Implementations and overrides in \p Dec apply to \p DECRYPTION. + /// \class Dec + /// \brief Class specific methods used to operate the cipher in the reverse direction. + /// \details Implementations and overrides in \p Dec apply to \p DECRYPTION. class CRYPTOPP_NO_VTABLE Dec : public Base { public: diff --git a/adler32.h b/adler32.h index 3c62748b..0b906615 100644 --- a/adler32.h +++ b/adler32.h @@ -1,8 +1,8 @@ // adler32.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile adler32.h -//! \brief Class file for ADLER-32 checksum calculations +/// \file +/// \headerfile adler32.h +/// \brief Class file for ADLER-32 checksum calculations #ifndef CRYPTOPP_ADLER32_H #define CRYPTOPP_ADLER32_H @@ -11,7 +11,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! ADLER-32 checksum calculations +/// ADLER-32 checksum calculations class Adler32 : public HashTransformation { public: diff --git a/aes.h b/aes.h index 274f67c6..ee603fa2 100644 --- a/aes.h +++ b/aes.h @@ -1,10 +1,10 @@ // aes.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \brief Class file for the AES cipher (Rijndael) -//! \details AES is a typdef for Rijndael classes. All key sizes are supported. -//! The library only provides Rijndael with 128-bit blocks, and not 192-bit or 256-bit blocks -//! \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0 +/// \file +/// \brief Class file for the AES cipher (Rijndael) +/// \details AES is a typdef for Rijndael classes. All key sizes are supported. +/// The library only provides Rijndael with 128-bit blocks, and not 192-bit or 256-bit blocks +/// \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0 #ifndef CRYPTOPP_AES_H #define CRYPTOPP_AES_H @@ -13,12 +13,12 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class AES -//! \brief AES block cipher (Rijndael) -//! \details AES is a typdef for Rijndael classes. All key sizes are supported. -//! The library only provides Rijndael with 128-bit blocks, and not 192-bit or 256-bit blocks -//! \sa AES winner, announced on 10/2/2000 -//! \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0 +/// \class AES +/// \brief AES block cipher (Rijndael) +/// \details AES is a typdef for Rijndael classes. All key sizes are supported. +/// The library only provides Rijndael with 128-bit blocks, and not 192-bit or 256-bit blocks +/// \sa AES winner, announced on 10/2/2000 +/// \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0 DOCUMENTED_TYPEDEF(Rijndael, AES) typedef RijndaelEncryption AESEncryption; diff --git a/algebra.h b/algebra.h index f1d846b4..0c4da2ba 100644 --- a/algebra.h +++ b/algebra.h @@ -1,7 +1,7 @@ // algebra.h - originally written and placed in the public domain by Wei Dai -//! \file algebra.h -//! \brief Classes for performing mathematics over different fields +/// \file algebra.h +/// \brief Classes for performing mathematics over different fields #ifndef CRYPTOPP_ALGEBRA_H #define CRYPTOPP_ALGEBRA_H @@ -14,15 +14,15 @@ NAMESPACE_BEGIN(CryptoPP) class Integer; -//! \brief Abstract group -//! \tparam T element class or type -//! \details const Element& returned by member functions are references -//! to internal data members. Since each object may have only -//! one such data member for holding results, the following code -//! will produce incorrect results: -//! 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
-//! But this should be fine: -//! 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
+/// \brief Abstract group +/// \tparam T element class or type +/// \details const Element& returned by member functions are references +/// to internal data members. Since each object may have only +/// one such data member for holding results, the following code +/// will produce incorrect results: +/// 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
+/// But this should be fine: +/// 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
template class CRYPTOPP_NO_VTABLE AbstractGroup { public: @@ -30,167 +30,167 @@ public: virtual ~AbstractGroup() {} - //! \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 + /// \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 virtual bool Equal(const Element &a, const Element &b) const =0; - //! \brief Provides the Identity element - //! \returns the Identity element + /// \brief Provides the Identity element + /// \returns the Identity element virtual const Element& Identity() const =0; - //! \brief Adds elements in the group - //! \param a first element - //! \param b second element - //! \returns the sum of a and b + /// \brief Adds elements in the group + /// \param a first element + /// \param b second element + /// \returns the sum of a and b virtual const Element& Add(const Element &a, const Element &b) const =0; - //! \brief Inverts the element in the group - //! \param a first element - //! \returns the inverse of the element + /// \brief Inverts the element in the group + /// \param a first element + /// \returns the inverse of the element virtual const Element& Inverse(const Element &a) const =0; - //! \brief Determine if inversion is fast - //! \returns true if inversion is fast, false otherwise + /// \brief Determine if inversion is fast + /// \returns true if inversion is fast, false otherwise virtual bool InversionIsFast() const {return false;} - //! \brief Doubles an element in the group - //! \param a the element - //! \returns the element doubled + /// \brief Doubles an element in the group + /// \param a the element + /// \returns the element doubled virtual const Element& Double(const Element &a) const; - //! \brief Subtracts elements in the group - //! \param a first element - //! \param b second element - //! \returns the difference of a and b. The element a must provide a Subtract member function. + /// \brief Subtracts elements in the group + /// \param a first element + /// \param b second element + /// \returns the difference of a and b. The element a must provide a Subtract member function. virtual const Element& Subtract(const Element &a, const Element &b) const; - //! \brief TODO - //! \param a first element - //! \param b second element - //! \returns TODO + /// \brief TODO + /// \param a first element + /// \param b second element + /// \returns TODO virtual Element& Accumulate(Element &a, const Element &b) const; - //! \brief Reduces an element in the congruence class - //! \param a element to reduce - //! \param b the congruence class - //! \returns the reduced element + /// \brief Reduces an element in the congruence class + /// \param a element to reduce + /// \param b the congruence class + /// \returns the reduced element virtual Element& Reduce(Element &a, const Element &b) const; - //! \brief Performs a scalar multiplication - //! \param a multiplicand - //! \param e multiplier - //! \returns the product + /// \brief Performs a scalar multiplication + /// \param a multiplicand + /// \param e multiplier + /// \returns the product virtual Element ScalarMultiply(const Element &a, const Integer &e) const; - //! \brief TODO - //! \param x first multiplicand - //! \param e1 the first multiplier - //! \param y second multiplicand - //! \param e2 the second multiplier - //! \returns TODO + /// \brief TODO + /// \param x first multiplicand + /// \param e1 the first multiplier + /// \param y second multiplicand + /// \param e2 the second multiplier + /// \returns TODO virtual Element CascadeScalarMultiply(const Element &x, const Integer &e1, const Element &y, const Integer &e2) const; - //! \brief Multiplies a base to multiple exponents in a group - //! \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 SimultaneousMultiply() multiplies the base to each exponent in the exponents array and stores the - //! result at the respective position in the results array. - //! \details SimultaneousMultiply() must be implemented in a derived class. - //! \pre COUNTOF(results) == exponentsCount - //! \pre COUNTOF(exponents) == exponentsCount + /// \brief Multiplies a base to multiple exponents in a group + /// \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 SimultaneousMultiply() multiplies the base to each exponent in the exponents array and stores the + /// result at the respective position in the results array. + /// \details SimultaneousMultiply() must be implemented in a derived class. + /// \pre COUNTOF(results) == exponentsCount + /// \pre COUNTOF(exponents) == exponentsCount virtual void SimultaneousMultiply(Element *results, const Element &base, const Integer *exponents, unsigned int exponentsCount) const; }; -//! \brief Abstract ring -//! \tparam T element class or type -//! \details const Element& returned by member functions are references -//! to internal data members. Since each object may have only -//! one such data member for holding results, the following code -//! will produce incorrect results: -//! 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
-//! But this should be fine: -//! 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
+/// \brief Abstract ring +/// \tparam T element class or type +/// \details const Element& returned by member functions are references +/// to internal data members. Since each object may have only +/// one such data member for holding results, the following code +/// will produce incorrect results: +/// 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
+/// But this should be fine: +/// 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
template class CRYPTOPP_NO_VTABLE AbstractRing : public AbstractGroup { public: typedef T Element; - //! \brief Construct an AbstractRing + /// \brief Construct an AbstractRing AbstractRing() {m_mg.m_pRing = this;} - //! \brief Copy construct an AbstractRing - //! \param source other AbstractRing + /// \brief Copy construct an AbstractRing + /// \param source other AbstractRing AbstractRing(const AbstractRing &source) {CRYPTOPP_UNUSED(source); m_mg.m_pRing = this;} - //! \brief Assign an AbstractRing - //! \param source other AbstractRing + /// \brief Assign an AbstractRing + /// \param source other AbstractRing AbstractRing& operator=(const AbstractRing &source) {CRYPTOPP_UNUSED(source); return *this;} - //! \brief Determines whether an element is a unit in the group - //! \param a the element - //! \returns true if the element is a unit after reduction, false otherwise. + /// \brief Determines whether an element is a unit in the group + /// \param a the element + /// \returns true if the element is a unit after reduction, false otherwise. virtual bool IsUnit(const Element &a) const =0; - //! \brief Retrieves the multiplicative identity - //! \returns the multiplicative identity + /// \brief Retrieves the multiplicative identity + /// \returns the multiplicative identity virtual const Element& MultiplicativeIdentity() const =0; - //! \brief Multiplies elements in the group - //! \param a the multiplicand - //! \param b the multiplier - //! \returns the product of a and b + /// \brief Multiplies elements in the group + /// \param a the multiplicand + /// \param b the multiplier + /// \returns the product of a and b virtual const Element& Multiply(const Element &a, const Element &b) const =0; - //! \brief Calculate the multiplicative inverse of an element in the group - //! \param a the element + /// \brief Calculate the multiplicative inverse of an element in the group + /// \param a the element virtual const Element& MultiplicativeInverse(const Element &a) const =0; - //! \brief Square an element in the group - //! \param a the element - //! \returns the element squared + /// \brief Square an element in the group + /// \param a the element + /// \returns the element squared virtual const Element& Square(const Element &a) const; - //! \brief Divides elements in the group - //! \param a the dividend - //! \param b the divisor - //! \returns the quotient + /// \brief Divides elements in the group + /// \param a the dividend + /// \param b the divisor + /// \returns the quotient virtual const Element& Divide(const Element &a, const Element &b) const; - //! \brief Raises a base to an exponent in the group - //! \param a the base - //! \param e the exponent - //! \returns the exponentiation + /// \brief Raises a base to an exponent in the group + /// \param a the base + /// \param e the exponent + /// \returns the exponentiation virtual Element Exponentiate(const Element &a, const Integer &e) const; - //! \brief TODO - //! \param x first element - //! \param e1 first exponent - //! \param y second element - //! \param e2 second exponent - //! \returns TODO + /// \brief TODO + /// \param x first element + /// \param e1 first exponent + /// \param y second element + /// \param e2 second exponent + /// \returns TODO virtual Element CascadeExponentiate(const Element &x, const Integer &e1, const Element &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 + /// \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 virtual void SimultaneousExponentiate(Element *results, const Element &base, const Integer *exponents, unsigned int exponentsCount) const; - //! \brief Retrieves the multiplicative group - //! \returns the multiplicative group + /// \brief Retrieves the multiplicative group + /// \returns the multiplicative group virtual const AbstractGroup& MultiplicativeGroup() const {return m_mg;} @@ -242,9 +242,9 @@ private: // ******************************************************** -//! \brief Base and exponent -//! \tparam T base class or type -//! \tparam E exponent class or type +/// \brief Base and exponent +/// \tparam T base class or type +/// \tparam E exponent class or type template struct BaseAndExponent { @@ -264,37 +264,37 @@ template // ******************************************************** -//! \brief Abstract Euclidean domain -//! \tparam T element class or type -//! \details const Element& returned by member functions are references -//! to internal data members. Since each object may have only -//! one such data member for holding results, the following code -//! will produce incorrect results: -//! 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
-//! But this should be fine: -//! 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
+/// \brief Abstract Euclidean domain +/// \tparam T element class or type +/// \details const Element& returned by member functions are references +/// to internal data members. Since each object may have only +/// one such data member for holding results, the following code +/// will produce incorrect results: +/// 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
+/// But this should be fine: +/// 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
template class CRYPTOPP_NO_VTABLE AbstractEuclideanDomain : public AbstractRing { public: typedef T Element; - //! \brief Performs the division algorithm on two elements in the ring - //! \param r the remainder - //! \param q the quotient - //! \param a the dividend - //! \param d the divisor + /// \brief Performs the division algorithm on two elements in the ring + /// \param r the remainder + /// \param q the quotient + /// \param a the dividend + /// \param d the divisor virtual void DivisionAlgorithm(Element &r, Element &q, const Element &a, const Element &d) const =0; - //! \brief Performs a modular reduction in the ring - //! \param a the element - //! \param b the modulus - //! \returns the result of a%b. + /// \brief Performs a modular reduction in the ring + /// \param a the element + /// \param b the modulus + /// \returns the result of a%b. virtual const Element& Mod(const Element &a, const Element &b) const =0; - //! \brief Calculates the greatest common denominator in the ring - //! \param a the first element - //! \param b the second element - //! \returns the the greatest common denominator of a and b. + /// \brief Calculates the greatest common denominator in the ring + /// \param a the first element + /// \param b the second element + /// \returns the the greatest common denominator of a and b. virtual const Element& Gcd(const Element &a, const Element &b) const; protected: @@ -303,15 +303,15 @@ protected: // ******************************************************** -//! \brief Euclidean domain -//! \tparam T element class or type -//! \details const Element& returned by member functions are references -//! to internal data members. Since each object may have only -//! one such data member for holding results, the following code -//! will produce incorrect results: -//! 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
-//! But this should be fine: -//! 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
+/// \brief Euclidean domain +/// \tparam T element class or type +/// \details const Element& returned by member functions are references +/// to internal data members. Since each object may have only +/// one such data member for holding results, the following code +/// will produce incorrect results: +/// 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
+/// But this should be fine: +/// 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
template class EuclideanDomainOf : public AbstractEuclideanDomain { public: @@ -374,15 +374,15 @@ private: mutable Element result; }; -//! \brief Quotient ring -//! \tparam T element class or type -//! \details const Element& returned by member functions are references -//! to internal data members. Since each object may have only -//! one such data member for holding results, the following code -//! will produce incorrect results: -//! 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
-//! But this should be fine: -//! 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
+/// \brief Quotient ring +/// \tparam T element class or type +/// \details const Element& returned by member functions are references +/// to internal data members. Since each object may have only +/// one such data member for holding results, the following code +/// will produce incorrect results: +/// 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
+/// But this should be fine: +/// 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
template class QuotientRing : public AbstractRing { public: diff --git a/algparam.h b/algparam.h index 615915d5..8cbb736e 100644 --- a/algparam.h +++ b/algparam.h @@ -1,8 +1,8 @@ // algparam.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile algparam.h -//! \brief Classes for working with NameValuePairs +/// \file +/// \headerfile algparam.h +/// \brief Classes for working with NameValuePairs #ifndef CRYPTOPP_ALGPARAM_H @@ -26,40 +26,40 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ConstByteArrayParameter -//! \brief Used to pass byte array input as part of a NameValuePairs object +/// \class ConstByteArrayParameter +/// \brief Used to pass byte array input as part of a NameValuePairs object class ConstByteArrayParameter { public: - //! \brief Construct a ConstByteArrayParameter - //! \param data a C-String - //! \param deepCopy flag indicating whether the data should be copied - //! \details The deepCopy option is used when the NameValuePairs object can't - //! keep a copy of the data available + /// \brief Construct a ConstByteArrayParameter + /// \param data a C-String + /// \param deepCopy flag indicating whether the data should be copied + /// \details The deepCopy option is used when the NameValuePairs object can't + /// keep a copy of the data available ConstByteArrayParameter(const char *data = NULLPTR, bool deepCopy = false) : m_deepCopy(false), m_data(NULLPTR), m_size(0) { Assign((const byte *)data, data ? strlen(data) : 0, deepCopy); } - //! \brief Construct a ConstByteArrayParameter - //! \param data a memory buffer - //! \param size the length of the memory buffer - //! \param deepCopy flag indicating whether the data should be copied - //! \details The deepCopy option is used when the NameValuePairs object can't - //! keep a copy of the data available + /// \brief Construct a ConstByteArrayParameter + /// \param data a memory buffer + /// \param size the length of the memory buffer + /// \param deepCopy flag indicating whether the data should be copied + /// \details The deepCopy option is used when the NameValuePairs object can't + /// keep a copy of the data available ConstByteArrayParameter(const byte *data, size_t size, bool deepCopy = false) : m_deepCopy(false), m_data(NULLPTR), m_size(0) { Assign(data, size, deepCopy); } - //! \brief Construct a ConstByteArrayParameter - //! \tparam T a std::basic_string class - //! \param string a std::basic_string class - //! \param deepCopy flag indicating whether the data should be copied - //! \details The deepCopy option is used when the NameValuePairs object can't - //! keep a copy of the data available + /// \brief Construct a ConstByteArrayParameter + /// \tparam T a std::basic_string class + /// \param string a std::basic_string class + /// \param deepCopy flag indicating whether the data should be copied + /// \details The deepCopy option is used when the NameValuePairs object can't + /// keep a copy of the data available template ConstByteArrayParameter(const T &string, bool deepCopy = false) : m_deepCopy(false), m_data(NULLPTR), m_size(0) { @@ -67,12 +67,12 @@ public: Assign((const byte *)string.data(), string.size(), deepCopy); } - //! \brief Assign contents from a memory buffer - //! \param data a memory buffer - //! \param size the length of the memory buffer - //! \param deepCopy flag indicating whether the data should be copied - //! \details The deepCopy option is used when the NameValuePairs object can't - //! keep a copy of the data available + /// \brief Assign contents from a memory buffer + /// \param data a memory buffer + /// \param size the length of the memory buffer + /// \param deepCopy flag indicating whether the data should be copied + /// \details The deepCopy option is used when the NameValuePairs object can't + /// keep a copy of the data available void Assign(const byte *data, size_t size, bool deepCopy) { // This fires, which means: no data with a size, or data with no size. @@ -87,11 +87,11 @@ public: m_deepCopy = deepCopy; } - //! \brief Pointer to the first byte in the memory block + /// \brief Pointer to the first byte in the memory block const byte *begin() const {return m_deepCopy ? m_block.begin() : m_data;} - //! \brief Pointer beyond the last byte in the memory block + /// \brief Pointer beyond the last byte in the memory block const byte *end() const {return m_deepCopy ? m_block.end() : m_data + m_size;} - //! \brief Length of the memory block + /// \brief Length of the memory block size_t size() const {return m_deepCopy ? m_block.size() : m_size;} private: @@ -101,27 +101,27 @@ private: SecByteBlock m_block; }; -//! \class ByteArrayParameter -//! \brief Used to pass byte array input as part of a NameValuePairs object +/// \class ByteArrayParameter +/// \brief Used to pass byte array input as part of a NameValuePairs object class ByteArrayParameter { public: - //! \brief Construct a ByteArrayParameter - //! \param data a memory buffer - //! \param size the length of the memory buffer + /// \brief Construct a ByteArrayParameter + /// \param data a memory buffer + /// \param size the length of the memory buffer ByteArrayParameter(byte *data = NULLPTR, unsigned int size = 0) : m_data(data), m_size(size) {} - //! \brief Construct a ByteArrayParameter - //! \param block a SecByteBlock + /// \brief Construct a ByteArrayParameter + /// \param block a SecByteBlock ByteArrayParameter(SecByteBlock &block) : m_data(block.begin()), m_size(block.size()) {} - //! \brief Pointer to the first byte in the memory block + /// \brief Pointer to the first byte in the memory block byte *begin() const {return m_data;} - //! \brief Pointer beyond the last byte in the memory block + /// \brief Pointer beyond the last byte in the memory block byte *end() const {return m_data + m_size;} - //! \brief Length of the memory block + /// \brief Length of the memory block size_t size() const {return m_size;} private: @@ -129,17 +129,17 @@ private: size_t m_size; }; -//! \class CombinedNameValuePairs -//! \brief Combines two sets of NameValuePairs -//! \details CombinedNameValuePairs allows you to provide two sets of of NameValuePairs. -//! If a name is not found in the first set, then the second set is searched for the -//! name and value pair. The second set of NameValuePairs often provides default values. +/// \class CombinedNameValuePairs +/// \brief Combines two sets of NameValuePairs +/// \details CombinedNameValuePairs allows you to provide two sets of of NameValuePairs. +/// If a name is not found in the first set, then the second set is searched for the +/// name and value pair. The second set of NameValuePairs often provides default values. class CRYPTOPP_DLL CombinedNameValuePairs : public NameValuePairs { public: - //! \brief Construct a CombinedNameValuePairs - //! \param pairs1 reference to the first set of NameValuePairs - //! \param pairs2 reference to the second set of NameValuePairs + /// \brief Construct a CombinedNameValuePairs + /// \param pairs1 reference to the first set of NameValuePairs + /// \param pairs2 reference to the second set of NameValuePairs CombinedNameValuePairs(const NameValuePairs &pairs1, const NameValuePairs &pairs2) : m_pairs1(pairs1), m_pairs2(pairs2) {} @@ -308,13 +308,13 @@ CRYPTOPP_DLL bool AssignIntToInteger(const std::type_info &valueType, void *pInt CRYPTOPP_DLL const std::type_info & CRYPTOPP_API IntegerTypeId(); -//! \class AlgorithmParametersBase -//! \brief Base class for AlgorithmParameters +/// \class AlgorithmParametersBase +/// \brief Base class for AlgorithmParameters class CRYPTOPP_DLL AlgorithmParametersBase { public: - //! \class ParameterNotUsed - //! \brief Exception thrown when an AlgorithmParameter is unused + /// \class ParameterNotUsed + /// \brief Exception thrown when an AlgorithmParameter is unused class ParameterNotUsed : public Exception { public: @@ -347,11 +347,11 @@ public: x.m_used = true; } - //! \brief Construct a AlgorithmParametersBase - //! \param name the parameter name - //! \param throwIfNotUsed flags indicating whether an exception should be thrown - //! \details If throwIfNotUsed is true, then a ParameterNotUsed exception - //! will be thrown in the destructor if the parameter is not not retrieved. + /// \brief Construct a AlgorithmParametersBase + /// \param name the parameter name + /// \param throwIfNotUsed flags indicating whether an exception should be thrown + /// \details If throwIfNotUsed is true, then a ParameterNotUsed exception + /// will be thrown in the destructor if the parameter is not not retrieved. AlgorithmParametersBase(const char *name, bool throwIfNotUsed) : m_name(name), m_throwIfNotUsed(throwIfNotUsed), m_used(false) {} @@ -370,19 +370,19 @@ protected: member_ptr m_next; }; -//! \class AlgorithmParametersTemplate -//! \brief Template base class for AlgorithmParameters -//! \tparam T the class or type +/// \class AlgorithmParametersTemplate +/// \brief Template base class for AlgorithmParameters +/// \tparam T the class or type template class AlgorithmParametersTemplate : public AlgorithmParametersBase { public: - //! \brief Construct an AlgorithmParametersTemplate - //! \param name the name of the value - //! \param value a reference to the value - //! \param throwIfNotUsed flags indicating whether an exception should be thrown - //! \details If throwIfNotUsed is true, then a ParameterNotUsed exception - //! will be thrown in the destructor if the parameter is not not retrieved. + /// \brief Construct an AlgorithmParametersTemplate + /// \param name the name of the value + /// \param value a reference to the value + /// \param throwIfNotUsed flags indicating whether an exception should be thrown + /// \details If throwIfNotUsed is true, then a ParameterNotUsed exception + /// will be thrown in the destructor if the parameter is not not retrieved. AlgorithmParametersTemplate(const char *name, const T &value, bool throwIfNotUsed) : AlgorithmParametersBase(name, throwIfNotUsed), m_value(value) { @@ -423,37 +423,37 @@ CRYPTOPP_DLL_TEMPLATE_CLASS AlgorithmParametersTemplate; CRYPTOPP_DLL_TEMPLATE_CLASS AlgorithmParametersTemplate; CRYPTOPP_DLL_TEMPLATE_CLASS AlgorithmParametersTemplate; -//! \class AlgorithmParameters -//! \brief An object that implements NameValuePairs -//! \note A NameValuePairs object containing an arbitrary number of name value pairs may be constructed by -//! repeatedly using operator() on the object returned by MakeParameters, for example: -//! 
-//!     AlgorithmParameters parameters = MakeParameters(name1, value1)(name2, value2)(name3, value3);
-//!
+/// \class AlgorithmParameters +/// \brief An object that implements NameValuePairs +/// \note A NameValuePairs object containing an arbitrary number of name value pairs may be constructed by +/// repeatedly using operator() on the object returned by MakeParameters, for example: +/// 
+///     AlgorithmParameters parameters = MakeParameters(name1, value1)(name2, value2)(name3, value3);
+///
class CRYPTOPP_DLL AlgorithmParameters : public NameValuePairs { public: - //! \brief Construct a AlgorithmParameters - //! \note A NameValuePairs object containing an arbitrary number of name value pairs may be constructed by - //! repeatedly using operator() on the object returned by MakeParameters, for example: - //! 
-	//!     AlgorithmParameters parameters = MakeParameters(name1, value1)(name2, value2)(name3, value3);
-	//!
+ /// \brief Construct a AlgorithmParameters + /// \note A NameValuePairs object containing an arbitrary number of name value pairs may be constructed by + /// repeatedly using operator() on the object returned by MakeParameters, for example: + /// 
+	///     AlgorithmParameters parameters = MakeParameters(name1, value1)(name2, value2)(name3, value3);
+	///
AlgorithmParameters(); #ifdef __BORLANDC__ - //! \brief Construct a AlgorithmParameters - //! \tparam T the class or type - //! \param name the name of the object or value to retrieve - //! \param value reference to a variable that receives the value - //! \param throwIfNotUsed if true, the object will throw an exception if the value is not accessed - //! \note throwIfNotUsed is ignored if using a compiler that does not support std::uncaught_exception(), - //! such as MSVC 7.0 and earlier. - //! \note A NameValuePairs object containing an arbitrary number of name value pairs may be constructed by - //! repeatedly using operator() on the object returned by MakeParameters, for example: - //! 
-	//!     AlgorithmParameters parameters = MakeParameters(name1, value1)(name2, value2)(name3, value3);
-	//!
+ /// \brief Construct a AlgorithmParameters + /// \tparam T the class or type + /// \param name the name of the object or value to retrieve + /// \param value reference to a variable that receives the value + /// \param throwIfNotUsed if true, the object will throw an exception if the value is not accessed + /// \note throwIfNotUsed is ignored if using a compiler that does not support std::uncaught_exception(), + /// such as MSVC 7.0 and earlier. + /// \note A NameValuePairs object containing an arbitrary number of name value pairs may be constructed by + /// repeatedly using operator() on the object returned by MakeParameters, for example: + /// 
+	///     AlgorithmParameters parameters = MakeParameters(name1, value1)(name2, value2)(name3, value3);
+	///
template AlgorithmParameters(const char *name, const T &value, bool throwIfNotUsed=true) : m_next(new AlgorithmParametersTemplate(name, value, throwIfNotUsed)) @@ -466,10 +466,10 @@ public: AlgorithmParameters & operator=(const AlgorithmParameters &x); - //! \tparam T the class or type - //! \param name the name of the object or value to retrieve - //! \param value reference to a variable that receives the value - //! \param throwIfNotUsed if true, the object will throw an exception if the value is not accessed + /// \tparam T the class or type + /// \param name the name of the object or value to retrieve + /// \param value reference to a variable that receives the value + /// \param throwIfNotUsed if true, the object will throw an exception if the value is not accessed template AlgorithmParameters & operator()(const char *name, const T &value, bool throwIfNotUsed) { @@ -480,10 +480,10 @@ public: return *this; } - //! \brief Appends a NameValuePair to a collection of NameValuePairs - //! \tparam T the class or type - //! \param name the name of the object or value to retrieve - //! \param value reference to a variable that receives the value + /// \brief Appends a NameValuePair to a collection of NameValuePairs + /// \tparam T the class or type + /// \param name the name of the object or value to retrieve + /// \param value reference to a variable that receives the value template AlgorithmParameters & operator()(const char *name, const T &value) { @@ -497,18 +497,18 @@ protected: bool m_defaultThrowIfNotUsed; }; -//! \brief Create an object that implements NameValuePairs -//! \tparam T the class or type -//! \param name the name of the object or value to retrieve -//! \param value reference to a variable that receives the value -//! \param throwIfNotUsed if true, the object will throw an exception if the value is not accessed -//! \note throwIfNotUsed is ignored if using a compiler that does not support std::uncaught_exception(), -//! such as MSVC 7.0 and earlier. -//! \note A NameValuePairs object containing an arbitrary number of name value pairs may be constructed by -//! repeatedly using \p operator() on the object returned by \p MakeParameters, for example: -//! 
-//!     AlgorithmParameters parameters = MakeParameters(name1, value1)(name2, value2)(name3, value3);
-//!
+/// \brief Create an object that implements NameValuePairs +/// \tparam T the class or type +/// \param name the name of the object or value to retrieve +/// \param value reference to a variable that receives the value +/// \param throwIfNotUsed if true, the object will throw an exception if the value is not accessed +/// \note throwIfNotUsed is ignored if using a compiler that does not support std::uncaught_exception(), +/// such as MSVC 7.0 and earlier. +/// \note A NameValuePairs object containing an arbitrary number of name value pairs may be constructed by +/// repeatedly using \p operator() on the object returned by \p MakeParameters, for example: +/// 
+///     AlgorithmParameters parameters = MakeParameters(name1, value1)(name2, value2)(name3, value3);
+///
#ifdef __BORLANDC__ typedef AlgorithmParameters MakeParameters; #else diff --git a/arc4.h b/arc4.h index c406c1de..22a8f9e0 100644 --- a/arc4.h +++ b/arc4.h @@ -1,7 +1,7 @@ // arc4.h - originally written and placed in the public domain by Wei Dai -//! \file arc4.h -//! \brief Classes for ARC4 cipher +/// \file arc4.h +/// \brief Classes for ARC4 cipher #ifndef CRYPTOPP_ARC4_H #define CRYPTOPP_ARC4_H @@ -15,10 +15,10 @@ NAMESPACE_BEGIN(CryptoPP) namespace Weak1 { -//! \class ARC4_Base -//! \brief ARC4 base class -//! \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions -//! \since Crypto++ 1.0 +/// \class ARC4_Base +/// \brief ARC4 base class +/// \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions +/// \since Crypto++ 1.0 class CRYPTOPP_NO_VTABLE ARC4_Base : public VariableKeyLength<16, 1, 256>, public RandomNumberGenerator, public SymmetricCipher, public SymmetricCipherDocumentation { public: @@ -46,16 +46,16 @@ protected: byte m_x, m_y; }; -//! \class ARC4 -//! \brief Alleged RC4 -//! \sa Alleged RC4 -//! \since Crypto++ 1.0 +/// \class ARC4 +/// \brief Alleged RC4 +/// \sa Alleged RC4 +/// \since Crypto++ 1.0 DOCUMENTED_TYPEDEF(SymmetricCipherFinal, ARC4) -//! \class MARC4_Base -//! \brief MARC4 base class -//! \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions -//! \details MARC4 discards the first 256 bytes of keystream, which may be weaker than the rest +/// \class MARC4_Base +/// \brief MARC4 base class +/// \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions +/// \details MARC4 discards the first 256 bytes of keystream, which may be weaker than the rest class CRYPTOPP_NO_VTABLE MARC4_Base : public ARC4_Base { public: @@ -68,10 +68,10 @@ protected: unsigned int GetDefaultDiscardBytes() const {return 256;} }; -//! \class MARC4 -//! \brief Modified Alleged RC4 -//! \sa Alleged RC4 -//! \since Crypto++ 1.0 +/// \class MARC4 +/// \brief Modified Alleged RC4 +/// \sa Alleged RC4 +/// \since Crypto++ 1.0 DOCUMENTED_TYPEDEF(SymmetricCipherFinal, MARC4) } diff --git a/argnames.h b/argnames.h index 4b7a2928..3d2859a8 100644 --- a/argnames.h +++ b/argnames.h @@ -1,7 +1,7 @@ // argnames.h - originally written and placed in the public domain by Wei Dai -//! \file argnames.h -//! \brief Standard names for retrieving values by name when working with \p NameValuePairs +/// \file argnames.h +/// \brief Standard names for retrieving values by name when working with \p NameValuePairs #ifndef CRYPTOPP_ARGNAMES_H #define CRYPTOPP_ARGNAMES_H @@ -14,84 +14,84 @@ DOCUMENTED_NAMESPACE_BEGIN(Name) #define CRYPTOPP_DEFINE_NAME_STRING(name) inline const char *name() {return #name;} -CRYPTOPP_DEFINE_NAME_STRING(ValueNames) //!< string, a list of value names with a semicolon (';') after each name -CRYPTOPP_DEFINE_NAME_STRING(Version) //!< int -CRYPTOPP_DEFINE_NAME_STRING(Seed) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(Key) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(IV) //!< ConstByteArrayParameter, also accepts const byte * for backwards compatibility -CRYPTOPP_DEFINE_NAME_STRING(StolenIV) //!< byte * -CRYPTOPP_DEFINE_NAME_STRING(Nonce) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(Rounds) //!< int -CRYPTOPP_DEFINE_NAME_STRING(FeedbackSize) //!< int -CRYPTOPP_DEFINE_NAME_STRING(WordSize) //!< int, in bytes -CRYPTOPP_DEFINE_NAME_STRING(BlockSize) //!< int, in bytes -CRYPTOPP_DEFINE_NAME_STRING(EffectiveKeyLength) //!< int, in bits -CRYPTOPP_DEFINE_NAME_STRING(KeySize) //!< int, in bits -CRYPTOPP_DEFINE_NAME_STRING(ModulusSize) //!< int, in bits -CRYPTOPP_DEFINE_NAME_STRING(SubgroupOrderSize) //!< int, in bits -CRYPTOPP_DEFINE_NAME_STRING(PrivateExponentSize)//!< int, in bits -CRYPTOPP_DEFINE_NAME_STRING(Modulus) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(PublicExponent) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(PrivateExponent) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(PublicElement) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(SubgroupOrder) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(Cofactor) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(SubgroupGenerator) //!< Integer, ECP::Point, or EC2N::Point -CRYPTOPP_DEFINE_NAME_STRING(Curve) //!< ECP or EC2N -CRYPTOPP_DEFINE_NAME_STRING(GroupOID) //!< OID -CRYPTOPP_DEFINE_NAME_STRING(PointerToPrimeSelector) //!< const PrimeSelector * -CRYPTOPP_DEFINE_NAME_STRING(Prime1) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(Prime2) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(ModPrime1PrivateExponent) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(ModPrime2PrivateExponent) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(MultiplicativeInverseOfPrime2ModPrime1) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(QuadraticResidueModPrime1) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(QuadraticResidueModPrime2) //!< Integer -CRYPTOPP_DEFINE_NAME_STRING(PutMessage) //!< bool -CRYPTOPP_DEFINE_NAME_STRING(TruncatedDigestSize) //!< int -CRYPTOPP_DEFINE_NAME_STRING(BlockPaddingScheme) //!< StreamTransformationFilter::BlockPaddingScheme -CRYPTOPP_DEFINE_NAME_STRING(HashVerificationFilterFlags) //!< word32 -CRYPTOPP_DEFINE_NAME_STRING(AuthenticatedDecryptionFilterFlags) //!< word32 -CRYPTOPP_DEFINE_NAME_STRING(SignatureVerificationFilterFlags) //!< word32 -CRYPTOPP_DEFINE_NAME_STRING(InputBuffer) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(OutputBuffer) //!< ByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(InputFileName) //!< const char * -CRYPTOPP_DEFINE_NAME_STRING(InputFileNameWide) //!< const wchar_t * -CRYPTOPP_DEFINE_NAME_STRING(InputStreamPointer) //!< std::istream * -CRYPTOPP_DEFINE_NAME_STRING(InputBinaryMode) //!< bool -CRYPTOPP_DEFINE_NAME_STRING(OutputFileName) //!< const char * -CRYPTOPP_DEFINE_NAME_STRING(OutputFileNameWide) //!< const wchar_t * -CRYPTOPP_DEFINE_NAME_STRING(OutputStreamPointer) //!< std::ostream * -CRYPTOPP_DEFINE_NAME_STRING(OutputBinaryMode) //!< bool -CRYPTOPP_DEFINE_NAME_STRING(EncodingParameters) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(KeyDerivationParameters) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(Separator) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(Terminator) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(Uppercase) //!< bool -CRYPTOPP_DEFINE_NAME_STRING(GroupSize) //!< int -CRYPTOPP_DEFINE_NAME_STRING(Pad) //!< bool -CRYPTOPP_DEFINE_NAME_STRING(PaddingByte) //!< byte -CRYPTOPP_DEFINE_NAME_STRING(Log2Base) //!< int -CRYPTOPP_DEFINE_NAME_STRING(EncodingLookupArray) //!< const byte * -CRYPTOPP_DEFINE_NAME_STRING(DecodingLookupArray) //!< const byte * -CRYPTOPP_DEFINE_NAME_STRING(InsertLineBreaks) //!< bool -CRYPTOPP_DEFINE_NAME_STRING(MaxLineLength) //!< int -CRYPTOPP_DEFINE_NAME_STRING(DigestSize) //!< int, in bytes -CRYPTOPP_DEFINE_NAME_STRING(L1KeyLength) //!< int, in bytes -CRYPTOPP_DEFINE_NAME_STRING(TableSize) //!< int, in bytes -CRYPTOPP_DEFINE_NAME_STRING(Blinding) //!< bool, timing attack mitigations, ON by default -CRYPTOPP_DEFINE_NAME_STRING(DerivedKey) //!< ByteArrayParameter, key derivation, derived key -CRYPTOPP_DEFINE_NAME_STRING(DerivedKeyLength) //!< int, key derivation, derived key length in bytes -CRYPTOPP_DEFINE_NAME_STRING(Personalization) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(PersonalizationSize) //!< int, in bytes -CRYPTOPP_DEFINE_NAME_STRING(Salt) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(Tweak) //!< ConstByteArrayParameter -CRYPTOPP_DEFINE_NAME_STRING(SaltSize) //!< int, in bytes -CRYPTOPP_DEFINE_NAME_STRING(TreeMode) //!< byte -CRYPTOPP_DEFINE_NAME_STRING(FileName) //!< const char * -CRYPTOPP_DEFINE_NAME_STRING(FileTime) //!< int -CRYPTOPP_DEFINE_NAME_STRING(Comment) //!< const char * -CRYPTOPP_DEFINE_NAME_STRING(Identity) //!< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(ValueNames) ///< string, a list of value names with a semicolon (';') after each name +CRYPTOPP_DEFINE_NAME_STRING(Version) ///< int +CRYPTOPP_DEFINE_NAME_STRING(Seed) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(Key) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(IV) ///< ConstByteArrayParameter, also accepts const byte * for backwards compatibility +CRYPTOPP_DEFINE_NAME_STRING(StolenIV) ///< byte * +CRYPTOPP_DEFINE_NAME_STRING(Nonce) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(Rounds) ///< int +CRYPTOPP_DEFINE_NAME_STRING(FeedbackSize) ///< int +CRYPTOPP_DEFINE_NAME_STRING(WordSize) ///< int, in bytes +CRYPTOPP_DEFINE_NAME_STRING(BlockSize) ///< int, in bytes +CRYPTOPP_DEFINE_NAME_STRING(EffectiveKeyLength) ///< int, in bits +CRYPTOPP_DEFINE_NAME_STRING(KeySize) ///< int, in bits +CRYPTOPP_DEFINE_NAME_STRING(ModulusSize) ///< int, in bits +CRYPTOPP_DEFINE_NAME_STRING(SubgroupOrderSize) ///< int, in bits +CRYPTOPP_DEFINE_NAME_STRING(PrivateExponentSize)///< int, in bits +CRYPTOPP_DEFINE_NAME_STRING(Modulus) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(PublicExponent) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(PrivateExponent) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(PublicElement) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(SubgroupOrder) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(Cofactor) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(SubgroupGenerator) ///< Integer, ECP::Point, or EC2N::Point +CRYPTOPP_DEFINE_NAME_STRING(Curve) ///< ECP or EC2N +CRYPTOPP_DEFINE_NAME_STRING(GroupOID) ///< OID +CRYPTOPP_DEFINE_NAME_STRING(PointerToPrimeSelector) ///< const PrimeSelector * +CRYPTOPP_DEFINE_NAME_STRING(Prime1) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(Prime2) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(ModPrime1PrivateExponent) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(ModPrime2PrivateExponent) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(MultiplicativeInverseOfPrime2ModPrime1) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(QuadraticResidueModPrime1) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(QuadraticResidueModPrime2) ///< Integer +CRYPTOPP_DEFINE_NAME_STRING(PutMessage) ///< bool +CRYPTOPP_DEFINE_NAME_STRING(TruncatedDigestSize) ///< int +CRYPTOPP_DEFINE_NAME_STRING(BlockPaddingScheme) ///< StreamTransformationFilter::BlockPaddingScheme +CRYPTOPP_DEFINE_NAME_STRING(HashVerificationFilterFlags) ///< word32 +CRYPTOPP_DEFINE_NAME_STRING(AuthenticatedDecryptionFilterFlags) ///< word32 +CRYPTOPP_DEFINE_NAME_STRING(SignatureVerificationFilterFlags) ///< word32 +CRYPTOPP_DEFINE_NAME_STRING(InputBuffer) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(OutputBuffer) ///< ByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(InputFileName) ///< const char * +CRYPTOPP_DEFINE_NAME_STRING(InputFileNameWide) ///< const wchar_t * +CRYPTOPP_DEFINE_NAME_STRING(InputStreamPointer) ///< std::istream * +CRYPTOPP_DEFINE_NAME_STRING(InputBinaryMode) ///< bool +CRYPTOPP_DEFINE_NAME_STRING(OutputFileName) ///< const char * +CRYPTOPP_DEFINE_NAME_STRING(OutputFileNameWide) ///< const wchar_t * +CRYPTOPP_DEFINE_NAME_STRING(OutputStreamPointer) ///< std::ostream * +CRYPTOPP_DEFINE_NAME_STRING(OutputBinaryMode) ///< bool +CRYPTOPP_DEFINE_NAME_STRING(EncodingParameters) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(KeyDerivationParameters) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(Separator) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(Terminator) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(Uppercase) ///< bool +CRYPTOPP_DEFINE_NAME_STRING(GroupSize) ///< int +CRYPTOPP_DEFINE_NAME_STRING(Pad) ///< bool +CRYPTOPP_DEFINE_NAME_STRING(PaddingByte) ///< byte +CRYPTOPP_DEFINE_NAME_STRING(Log2Base) ///< int +CRYPTOPP_DEFINE_NAME_STRING(EncodingLookupArray) ///< const byte * +CRYPTOPP_DEFINE_NAME_STRING(DecodingLookupArray) ///< const byte * +CRYPTOPP_DEFINE_NAME_STRING(InsertLineBreaks) ///< bool +CRYPTOPP_DEFINE_NAME_STRING(MaxLineLength) ///< int +CRYPTOPP_DEFINE_NAME_STRING(DigestSize) ///< int, in bytes +CRYPTOPP_DEFINE_NAME_STRING(L1KeyLength) ///< int, in bytes +CRYPTOPP_DEFINE_NAME_STRING(TableSize) ///< int, in bytes +CRYPTOPP_DEFINE_NAME_STRING(Blinding) ///< bool, timing attack mitigations, ON by default +CRYPTOPP_DEFINE_NAME_STRING(DerivedKey) ///< ByteArrayParameter, key derivation, derived key +CRYPTOPP_DEFINE_NAME_STRING(DerivedKeyLength) ///< int, key derivation, derived key length in bytes +CRYPTOPP_DEFINE_NAME_STRING(Personalization) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(PersonalizationSize) ///< int, in bytes +CRYPTOPP_DEFINE_NAME_STRING(Salt) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(Tweak) ///< ConstByteArrayParameter +CRYPTOPP_DEFINE_NAME_STRING(SaltSize) ///< int, in bytes +CRYPTOPP_DEFINE_NAME_STRING(TreeMode) ///< byte +CRYPTOPP_DEFINE_NAME_STRING(FileName) ///< const char * +CRYPTOPP_DEFINE_NAME_STRING(FileTime) ///< int +CRYPTOPP_DEFINE_NAME_STRING(Comment) ///< const char * +CRYPTOPP_DEFINE_NAME_STRING(Identity) ///< ConstByteArrayParameter DOCUMENTED_NAMESPACE_END NAMESPACE_END diff --git a/aria.h b/aria.h index 46990f45..e4eaee99 100644 --- a/aria.h +++ b/aria.h @@ -1,14 +1,14 @@ // aria.h - written and placed in the public domain by Jeffrey Walton -//! \file aria.h -//! \brief Classes for the ARIA block cipher -//! \details The Crypto++ ARIA implementation is based on the 32-bit implementation by Aaram Yun -//! from the National Security Research Institute, KOREA. Aaram Yun's implementation is based on -//! the 8-bit implementation by Jin Hong. The source files are available in ARIA.zip from the Korea -//! Internet & Security Agency website. -//! \sa RFC 5794, A Description of the ARIA Encryption Algorithm, -//! Korea -//! Internet & Security Agency homepage +/// \file aria.h +/// \brief Classes for the ARIA block cipher +/// \details The Crypto++ ARIA implementation is based on the 32-bit implementation by Aaram Yun +/// from the National Security Research Institute, KOREA. Aaram Yun's implementation is based on +/// the 8-bit implementation by Jin Hong. The source files are available in ARIA.zip from the Korea +/// Internet & Security Agency website. +/// \sa RFC 5794, A Description of the ARIA Encryption Algorithm, +/// Korea +/// Internet & Security Agency homepage #ifndef CRYPTOPP_ARIA_H #define CRYPTOPP_ARIA_H @@ -19,25 +19,25 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ARIA_Info -//! \brief ARIA block cipher information -//! \since Crypto++ 6.0 +/// \class ARIA_Info +/// \brief ARIA block cipher information +/// \since Crypto++ 6.0 struct ARIA_Info : public FixedBlockSize<16>, public VariableKeyLength<16, 16, 32, 8> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "ARIA";} }; -//! \class ARIA -//! \brief ARIA block cipher -//! \details The Crypto++ ARIA implementation is based on the 32-bit implementation by Aaram Yun -//! from the National Security Research Institute, KOREA. Aaram Yun's implementation is based on -//! the 8-bit implementation by Jin Hong. The source files are available in ARIA.zip from the Korea -//! Internet & Security Agency website. -//! \sa RFC 5794, A Description of the ARIA Encryption Algorithm, -//! Korea -//! Internet & Security Agency homepage -//! \sa ARIA -//! \since Crypto++ 6.0 +/// \class ARIA +/// \brief ARIA block cipher +/// \details The Crypto++ ARIA implementation is based on the 32-bit implementation by Aaram Yun +/// from the National Security Research Institute, KOREA. Aaram Yun's implementation is based on +/// the 8-bit implementation by Jin Hong. The source files are available in ARIA.zip from the Korea +/// Internet & Security Agency website. +/// \sa RFC 5794, A Description of the ARIA Encryption Algorithm, +/// Korea +/// Internet & Security Agency homepage +/// \sa ARIA +/// \since Crypto++ 6.0 class ARIA : public ARIA_Info, public BlockCipherDocumentation { public: diff --git a/asn.h b/asn.h index 673b8042..66641997 100644 --- a/asn.h +++ b/asn.h @@ -1,7 +1,7 @@ // asn.h - originally written and placed in the public domain by Wei Dai -//! \file asn.h -//! \brief Classes and functions for working with ANS.1 objects +/// \file asn.h +/// \brief Classes and functions for working with ANS.1 objects #ifndef CRYPTOPP_ASN_H #define CRYPTOPP_ASN_H @@ -22,8 +22,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief ASN.1 types -//! \note These tags and flags are not complete +/// \brief ASN.1 types +/// \note These tags and flags are not complete enum ASNTag { BOOLEAN = 0x01, @@ -51,8 +51,8 @@ enum ASNTag GENERAL_STRING = 0x1b }; -//! \brief ASN.1 flags -//! \note These tags and flags are not complete +/// \brief ASN.1 flags +/// \note These tags and flags are not complete enum ASNIdFlag { UNIVERSAL = 0x00, @@ -65,140 +65,140 @@ enum ASNIdFlag PRIVATE = 0xc0 }; -//! \brief Raises a BERDecodeErr +/// \brief Raises a BERDecodeErr inline void BERDecodeError() {throw BERDecodeErr();} -//! \brief Exception thrown when an unknown object identifier is encountered +/// \brief Exception thrown when an unknown object identifier is encountered class CRYPTOPP_DLL UnknownOID : public BERDecodeErr { public: - //! \brief Construct an UnknownOID + /// \brief Construct an UnknownOID UnknownOID() : BERDecodeErr("BER decode error: unknown object identifier") {} - //! \brief Construct an UnknownOID - //! \param err error message to use for the execption + /// \brief Construct an UnknownOID + /// \param err error message to use for the execption UnknownOID(const char *err) : BERDecodeErr(err) {} }; // unsigned int DERLengthEncode(unsigned int length, byte *output=0); -//! \brief DER encode a length -//! \param bt BufferedTransformation object for writing -//! \param length the size to encode -//! \returns the number of octets used for the encoding +/// \brief DER encode a length +/// \param bt BufferedTransformation object for writing +/// \param length the size to encode +/// \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API DERLengthEncode(BufferedTransformation &bt, lword length); -//! \brief BER decode a length -//! \param bt BufferedTransformation object for reading -//! \param length the decoded size -//! \returns true if the value was decoded -//! \throws BERDecodeError if the value fails to decode or is too large for size_t -//! \details BERLengthDecode() returns false if the encoding is indefinite length. +/// \brief BER decode a length +/// \param bt BufferedTransformation object for reading +/// \param length the decoded size +/// \returns true if the value was decoded +/// \throws BERDecodeError if the value fails to decode or is too large for size_t +/// \details BERLengthDecode() returns false if the encoding is indefinite length. CRYPTOPP_DLL bool CRYPTOPP_API BERLengthDecode(BufferedTransformation &bt, size_t &length); -//! \brief DER encode NULL -//! \param bt BufferedTransformation object for writing +/// \brief DER encode NULL +/// \param bt BufferedTransformation object for writing CRYPTOPP_DLL void CRYPTOPP_API DEREncodeNull(BufferedTransformation &bt); -//! \brief BER decode NULL -//! \param bt BufferedTransformation object for reading +/// \brief BER decode NULL +/// \param bt BufferedTransformation object for reading CRYPTOPP_DLL void CRYPTOPP_API BERDecodeNull(BufferedTransformation &bt); -//! \brief DER encode octet string -//! \param bt BufferedTransformation object for writing -//! \param str the string to encode -//! \param strLen the length of the string -//! \returns the number of octets used for the encoding +/// \brief DER encode octet string +/// \param bt BufferedTransformation object for writing +/// \param str the string to encode +/// \param strLen the length of the string +/// \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeOctetString(BufferedTransformation &bt, const byte *str, size_t strLen); -//! \brief DER encode octet string -//! \param bt BufferedTransformation object for reading -//! \param str the string to encode -//! \returns the number of octets used for the encoding +/// \brief DER encode octet string +/// \param bt BufferedTransformation object for reading +/// \param str the string to encode +/// \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeOctetString(BufferedTransformation &bt, const SecByteBlock &str); -//! \brief BER decode octet string -//! \param bt BufferedTransformation object for reading -//! \param str the decoded string -//! \returns the number of octets used for the encoding +/// \brief BER decode octet string +/// \param bt BufferedTransformation object for reading +/// \param str the decoded string +/// \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeOctetString(BufferedTransformation &bt, SecByteBlock &str); -//! \brief BER decode octet string -//! \param bt BufferedTransformation object for reading -//! \param str the decoded string -//! \returns the number of octets used for the encoding +/// \brief BER decode octet string +/// \param bt BufferedTransformation object for reading +/// \param str the decoded string +/// \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeOctetString(BufferedTransformation &bt, BufferedTransformation &str); -//! \brief DER encode text string -//! \param bt BufferedTransformation object for writing -//! \param str the string to encode -//! \param asnTag the ASN.1 type -//! \returns the number of octets used for the encoding -//! \details DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING +/// \brief DER encode text string +/// \param bt BufferedTransformation object for writing +/// \param str the string to encode +/// \param asnTag the ASN.1 type +/// \returns the number of octets used for the encoding +/// \details DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeTextString(BufferedTransformation &bt, const std::string &str, byte asnTag); -//! \brief BER decode text string -//! \param bt BufferedTransformation object for reading -//! \param str the string to encode -//! \param asnTag the ASN.1 type -//! \details DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING +/// \brief BER decode text string +/// \param bt BufferedTransformation object for reading +/// \param str the string to encode +/// \param asnTag the ASN.1 type +/// \details DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeTextString(BufferedTransformation &bt, std::string &str, byte asnTag); -//! \brief DER encode bit string -//! \param bt BufferedTransformation object for writing -//! \param str the string to encode -//! \param strLen the length of the string -//! \param unusedBits the number of unused bits -//! \returns the number of octets used for the encoding +/// \brief DER encode bit string +/// \param bt BufferedTransformation object for writing +/// \param str the string to encode +/// \param strLen the length of the string +/// \param unusedBits the number of unused bits +/// \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeBitString(BufferedTransformation &bt, const byte *str, size_t strLen, unsigned int unusedBits=0); -//! \brief DER decode bit string -//! \param bt BufferedTransformation object for reading -//! \param str the decoded string -//! \param unusedBits the number of unused bits +/// \brief DER decode bit string +/// \param bt BufferedTransformation object for reading +/// \param str the decoded string +/// \param unusedBits the number of unused bits CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeBitString(BufferedTransformation &bt, SecByteBlock &str, unsigned int &unusedBits); -//! \brief BER decode and DER re-encode -//! \param bt BufferedTransformation object for writing -//! \param dest BufferedTransformation object +/// \brief BER decode and DER re-encode +/// \param bt BufferedTransformation object for writing +/// \param dest BufferedTransformation object CRYPTOPP_DLL void CRYPTOPP_API DERReencode(BufferedTransformation &bt, BufferedTransformation &dest); -//! \brief Object Identifier +/// \brief Object Identifier class CRYPTOPP_DLL OID { public: virtual ~OID() {} - //! \brief Construct an OID + /// \brief Construct an OID OID() {} - //! \brief Construct an OID - //! \param v value to initialize the OID + /// \brief Construct an OID + /// \param v value to initialize the OID OID(word32 v) : m_values(1, v) {} - //! \brief Construct an OID - //! \param bt BufferedTransformation object + /// \brief Construct an OID + /// \param bt BufferedTransformation object OID(BufferedTransformation &bt) {BERDecode(bt);} - //! \brief Append a value to an OID - //! \param rhs the value to append + /// \brief Append a value to an OID + /// \param rhs the value to append inline OID & operator+=(word32 rhs) {m_values.push_back(rhs); return *this;} - //! \brief DER encode this OID - //! \param bt BufferedTransformation object + /// \brief DER encode this OID + /// \param bt BufferedTransformation object void DEREncode(BufferedTransformation &bt) const; - //! \brief BER decode an OID - //! \param bt BufferedTransformation object + /// \brief BER decode an OID + /// \param bt BufferedTransformation object void BERDecode(BufferedTransformation &bt); - //! \brief BER decode an OID - //! \param bt BufferedTransformation object - //! \throws BERDecodeErr() if decoded value doesn't match an expected OID - //! \details BERDecodeAndCheck() can be used to parse an OID and verify it matches an expected. - //! 
-	//!   BERSequenceDecoder key(bt);
-	//!   ...
-	//!   BERSequenceDecoder algorithm(key);
-	//!   GetAlgorithmID().BERDecodeAndCheck(algorithm);
-	//!
+ /// \brief BER decode an OID + /// \param bt BufferedTransformation object + /// \throws BERDecodeErr() if decoded value doesn't match an expected OID + /// \details BERDecodeAndCheck() can be used to parse an OID and verify it matches an expected. + /// 
+	///   BERSequenceDecoder key(bt);
+	///   ...
+	///   BERSequenceDecoder algorithm(key);
+	///   GetAlgorithmID().BERDecodeAndCheck(algorithm);
+	///
void BERDecodeAndCheck(BufferedTransformation &bt) const; std::vector m_values; @@ -208,7 +208,7 @@ private: static size_t DecodeValue(BufferedTransformation &bt, word32 &v); }; -//! \brief ASN.1 encoded object filter +/// \brief ASN.1 encoded object filter class EncodedObjectFilter : public Filter { public: @@ -216,15 +216,15 @@ public: virtual ~EncodedObjectFilter() {} - //! \brief Construct an EncodedObjectFilter - //! \param attachment a BufferedTrasformation to attach to this object - //! \param nObjects the number of objects - //! \param flags bitwise OR of EncodedObjectFilter::Flag + /// \brief Construct an EncodedObjectFilter + /// \param attachment a BufferedTrasformation to attach to this object + /// \param nObjects the number of objects + /// \param flags bitwise OR of EncodedObjectFilter::Flag EncodedObjectFilter(BufferedTransformation *attachment = NULLPTR, unsigned int nObjects = 1, word32 flags = 0); - //! \brief Input a byte buffer for processing - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes + /// \brief Input a byte buffer for processing + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes void Put(const byte *inString, size_t length); unsigned int GetNumberOfCompletedObjects() const {return m_nCurrentObject;} @@ -242,7 +242,7 @@ private: lword m_lengthRemaining; }; -//! \brief BER General Decoder +/// \brief BER General Decoder class CRYPTOPP_DLL BERGeneralDecoder : public Store { public: @@ -280,7 +280,7 @@ private: // proper direction. We did not break the library or versioning based on the output of // `nm --demangle libcryptopp.a | grep DERGeneralEncoder::DERGeneralEncoder | grep -v " U "`. -//! \brief DER General Encoder +/// \brief DER General Encoder class CRYPTOPP_DLL DERGeneralEncoder : public ByteQueue { public: @@ -299,7 +299,7 @@ private: byte m_asnTag; }; -//! \brief BER Sequence Decoder +/// \brief BER Sequence Decoder class CRYPTOPP_DLL BERSequenceDecoder : public BERGeneralDecoder { public: @@ -309,7 +309,7 @@ public: : BERGeneralDecoder(inQueue, asnTag) {} }; -//! \brief DER Sequence Encoder +/// \brief DER Sequence Encoder class CRYPTOPP_DLL DERSequenceEncoder : public DERGeneralEncoder { public: @@ -319,7 +319,7 @@ public: : DERGeneralEncoder(outQueue, asnTag) {} }; -//! \brief BER Set Decoder +/// \brief BER Set Decoder class CRYPTOPP_DLL BERSetDecoder : public BERGeneralDecoder { public: @@ -329,7 +329,7 @@ public: : BERGeneralDecoder(inQueue, asnTag) {} }; -//! \brief DER Set Encoder +/// \brief DER Set Encoder class CRYPTOPP_DLL DERSetEncoder : public DERGeneralEncoder { public: @@ -339,17 +339,17 @@ public: : DERGeneralEncoder(outQueue, asnTag) {} }; -//! \brief Optional data encoder and decoder -//! \tparam T class or type +/// \brief Optional data encoder and decoder +/// \tparam T class or type template class ASNOptional : public member_ptr { public: - //! \brief BER decode optional data - //! \param seqDecoder sequence with the optional ASN.1 data - //! \param tag ASN.1 tag to match as optional data - //! \param mask the mask to apply when matching the tag - //! \sa ASNTag and ASNIdFlag + /// \brief BER decode optional data + /// \param seqDecoder sequence with the optional ASN.1 data + /// \param tag ASN.1 tag to match as optional data + /// \param mask the mask to apply when matching the tag + /// \sa ASNTag and ASNIdFlag void BERDecode(BERSequenceDecoder &seqDecoder, byte tag, byte mask = ~CONSTRUCTED) { byte b; @@ -357,8 +357,8 @@ public: reset(new T(seqDecoder)); } - //! \brief DER encode optional data - //! \param out BufferedTransformation object + /// \brief DER encode optional data + /// \param out BufferedTransformation object void DEREncode(BufferedTransformation &out) { if (this->get() != NULLPTR) @@ -366,29 +366,29 @@ public: } }; -//! \brief Encode and decode ASN.1 objects with additional information -//! \tparam BASE base class or type -//! \details Encodes and decodes public keys, private keys and group -//! parameters with OID identifying the algorithm or scheme. +/// \brief Encode and decode ASN.1 objects with additional information +/// \tparam BASE base class or type +/// \details Encodes and decodes public keys, private keys and group +/// parameters with OID identifying the algorithm or scheme. template class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE ASN1CryptoMaterial : public ASN1Object, public BASE { public: - //! \brief DER encode ASN.1 object - //! \param bt BufferedTransformation object - //! \details Save() will write the OID associated with algorithm or scheme. - //! In the case of public and private keys, this function writes the - //! subjectPubicKeyInfo and privateKeyInfo parts. + /// \brief DER encode ASN.1 object + /// \param bt BufferedTransformation object + /// \details Save() will write the OID associated with algorithm or scheme. + /// In the case of public and private keys, this function writes the + /// subjectPubicKeyInfo and privateKeyInfo parts. void Save(BufferedTransformation &bt) const {BEREncode(bt);} - //! \brief BER decode ASN.1 object - //! \param bt BufferedTransformation object + /// \brief BER decode ASN.1 object + /// \param bt BufferedTransformation object void Load(BufferedTransformation &bt) {BERDecode(bt);} }; -//! \brief Encodes and decodes subjectPublicKeyInfo +/// \brief Encodes and decodes subjectPublicKeyInfo class CRYPTOPP_DLL X509PublicKey : public ASN1CryptoMaterial { public: @@ -397,21 +397,21 @@ public: void BERDecode(BufferedTransformation &bt); void DEREncode(BufferedTransformation &bt) const; - //! \brief Retrieves the OID of the algorithm - //! \returns OID of the algorithm + /// \brief Retrieves the OID of the algorithm + /// \returns OID of the algorithm virtual OID GetAlgorithmID() const =0; virtual bool BERDecodeAlgorithmParameters(BufferedTransformation &bt) {BERDecodeNull(bt); return false;} virtual bool DEREncodeAlgorithmParameters(BufferedTransformation &bt) const {DEREncodeNull(bt); return false;} // see RFC 2459, section 7.3.1 - //! decode subjectPublicKey part of subjectPublicKeyInfo, without the BIT STRING header + /// decode subjectPublicKey part of subjectPublicKeyInfo, without the BIT STRING header virtual void BERDecodePublicKey(BufferedTransformation &bt, bool parametersPresent, size_t size) =0; - //! encode subjectPublicKey part of subjectPublicKeyInfo, without the BIT STRING header + /// encode subjectPublicKey part of subjectPublicKeyInfo, without the BIT STRING header virtual void DEREncodePublicKey(BufferedTransformation &bt) const =0; }; -//! \brief Encodes and decodesprivateKeyInfo +/// \brief Encodes and decodesprivateKeyInfo class CRYPTOPP_DLL PKCS8PrivateKey : public ASN1CryptoMaterial { public: @@ -420,23 +420,23 @@ public: void BERDecode(BufferedTransformation &bt); void DEREncode(BufferedTransformation &bt) const; - //! \brief Retrieves the OID of the algorithm - //! \returns OID of the algorithm + /// \brief Retrieves the OID of the algorithm + /// \returns OID of the algorithm virtual OID GetAlgorithmID() const =0; virtual bool BERDecodeAlgorithmParameters(BufferedTransformation &bt) {BERDecodeNull(bt); return false;} virtual bool DEREncodeAlgorithmParameters(BufferedTransformation &bt) const {DEREncodeNull(bt); return false;} // see RFC 2459, section 7.3.1 - //! decode privateKey part of privateKeyInfo, without the OCTET STRING header + /// decode privateKey part of privateKeyInfo, without the OCTET STRING header virtual void BERDecodePrivateKey(BufferedTransformation &bt, bool parametersPresent, size_t size) =0; - //! encode privateKey part of privateKeyInfo, without the OCTET STRING header + /// encode privateKey part of privateKeyInfo, without the OCTET STRING header virtual void DEREncodePrivateKey(BufferedTransformation &bt) const =0; - //! decode optional attributes including context-specific tag + /// decode optional attributes including context-specific tag /*! /note default implementation stores attributes to be output in DEREncodeOptionalAttributes */ virtual void BERDecodeOptionalAttributes(BufferedTransformation &bt); - //! encode optional attributes including context-specific tag + /// encode optional attributes including context-specific tag virtual void DEREncodeOptionalAttributes(BufferedTransformation &bt) const; protected: @@ -445,12 +445,12 @@ protected: // ******************************************************** -//! \brief DER Encode unsigned value -//! \tparam T class or type -//! \param out BufferedTransformation object -//! \param w unsigned value to encode -//! \param asnTag the ASN.1 type -//! \details DEREncodeUnsigned() can be used with INTEGER, BOOLEAN, and ENUM +/// \brief DER Encode unsigned value +/// \tparam T class or type +/// \param out BufferedTransformation object +/// \param w unsigned value to encode +/// \param asnTag the ASN.1 type +/// \details DEREncodeUnsigned() can be used with INTEGER, BOOLEAN, and ENUM template size_t DEREncodeUnsigned(BufferedTransformation &out, T w, byte asnTag = INTEGER) { @@ -478,15 +478,15 @@ size_t DEREncodeUnsigned(BufferedTransformation &out, T w, byte asnTag = INTEGER return 1+lengthBytes+bc; } -//! \brief BER Decode unsigned value -//! \tparam T fundamental C++ type -//! \param in BufferedTransformation object -//! \param w the decoded value -//! \param asnTag the ASN.1 type -//! \param minValue the minimum expected value -//! \param maxValue the maximum expected value -//! \throws BERDecodeErr() if the value cannot be parsed or the decoded value is not within range. -//! \details DEREncodeUnsigned() can be used with INTEGER, BOOLEAN, and ENUM +/// \brief BER Decode unsigned value +/// \tparam T fundamental C++ type +/// \param in BufferedTransformation object +/// \param w the decoded value +/// \param asnTag the ASN.1 type +/// \param minValue the minimum expected value +/// \param maxValue the maximum expected value +/// \throws BERDecodeErr() if the value cannot be parsed or the decoded value is not within range. +/// \details DEREncodeUnsigned() can be used with INTEGER, BOOLEAN, and ENUM template void BERDecodeUnsigned(BufferedTransformation &in, T &w, byte asnTag = INTEGER, T minValue = 0, T maxValue = T(0xffffffff)) @@ -534,25 +534,25 @@ void BERDecodeUnsigned(BufferedTransformation &in, T &w, byte asnTag = INTEGER, } #ifdef CRYPTOPP_DOXYGEN_PROCESSING -//! \brief Compare two OIDs for equality -//! \param lhs the first OID -//! \param rhs the second OID -//! \returns true if the OIDs are equal, false otherwise +/// \brief Compare two OIDs for equality +/// \param lhs the first OID +/// \param rhs the second OID +/// \returns true if the OIDs are equal, false otherwise inline bool operator==(const OID &lhs, const OID &rhs); -//! \brief Compare two OIDs for inequality -//! \param lhs the first OID -//! \param rhs the second OID -//! \returns true if the OIDs are not equal, false otherwise +/// \brief Compare two OIDs for inequality +/// \param lhs the first OID +/// \param rhs the second OID +/// \returns true if the OIDs are not equal, false otherwise inline bool operator!=(const OID &lhs, const OID &rhs); -//! \brief Compare two OIDs for ordering -//! \param lhs the first OID -//! \param rhs the second OID -//! \returns true if the first OID is less than the second OID, false otherwise -//! \details operator<() calls std::lexicographical_compare() on each element in the array of values. +/// \brief Compare two OIDs for ordering +/// \param lhs the first OID +/// \param rhs the second OID +/// \returns true if the first OID is less than the second OID, false otherwise +/// \details operator<() calls std::lexicographical_compare() on each element in the array of values. inline bool operator<(const OID &lhs, const OID &rhs); -//! \brief Append a value to an OID -//! \param lhs the OID -//! \param rhs the value to append +/// \brief Append a value to an OID +/// \param lhs the OID +/// \param rhs the value to append inline OID operator+(const OID &lhs, unsigned long rhs); #else inline bool operator==(const ::CryptoPP::OID &lhs, const ::CryptoPP::OID &rhs) diff --git a/authenc.h b/authenc.h index 95ad590f..6ff87cf2 100644 --- a/authenc.h +++ b/authenc.h @@ -1,21 +1,21 @@ // authenc.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \brief Classes for authenticated encryption modes of operation -//! \details Authenticated encryption (AE) schemes combine confidentiality and authenticity -//! into a single mode of operation They gained traction in the early 2000's because manually -//! combining them was error prone for the typical developer. Around that time, the desire to -//! authenticate but not ecrypt additional data (AAD) was also identified. When both features -//! are available from a scheme, the system is referred to as an AEAD scheme. -//! \details Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM -//! and OCB mode. All modes derive from AuthenticatedSymmetricCipherBase() and the -//! motivation for the API, like calling AAD a "header", can be found in Bellare, -//! Rogaway and Wagner's The EAX -//! Mode of Operation. The EAX paper suggested a basic API to help standardize AEAD -//! schemes in software and promote adoption of the modes. -//! \sa Authenticated -//! Encryption on the Crypto++ wiki. -//! \since Crypto++ 5.6.0 +/// \file +/// \brief Classes for authenticated encryption modes of operation +/// \details Authenticated encryption (AE) schemes combine confidentiality and authenticity +/// into a single mode of operation They gained traction in the early 2000's because manually +/// combining them was error prone for the typical developer. Around that time, the desire to +/// authenticate but not ecrypt additional data (AAD) was also identified. When both features +/// are available from a scheme, the system is referred to as an AEAD scheme. +/// \details Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM +/// and OCB mode. All modes derive from AuthenticatedSymmetricCipherBase() and the +/// motivation for the API, like calling AAD a "header", can be found in Bellare, +/// Rogaway and Wagner's The EAX +/// Mode of Operation. The EAX paper suggested a basic API to help standardize AEAD +/// schemes in software and promote adoption of the modes. +/// \sa Authenticated +/// Encryption on the Crypto++ wiki. +/// \since Crypto++ 5.6.0 #ifndef CRYPTOPP_AUTHENC_H #define CRYPTOPP_AUTHENC_H @@ -25,19 +25,19 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class AuthenticatedSymmetricCipherBase -//! \brief Base class for authenticated encryption modes of operation -//! \details AuthenticatedSymmetricCipherBase() serves as a base implementation for one direction -//! (encryption or decryption) of a stream cipher or block cipher mode with authentication. -//! \details Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM -//! and OCB mode. All modes derive from AuthenticatedSymmetricCipherBase() and the -//! motivation for the API, like calling AAD a "header", can be found in Bellare, -//! Rogaway and Wagner's The EAX -//! Mode of Operation. The EAX paper suggested a basic API to help standardize AEAD -//! schemes in software and promote adoption of the modes. -//! \sa Authenticated -//! Encryption on the Crypto++ wiki. -//! \since Crypto++ 5.6.0 +/// \class AuthenticatedSymmetricCipherBase +/// \brief Base class for authenticated encryption modes of operation +/// \details AuthenticatedSymmetricCipherBase() serves as a base implementation for one direction +/// (encryption or decryption) of a stream cipher or block cipher mode with authentication. +/// \details Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM +/// and OCB mode. All modes derive from AuthenticatedSymmetricCipherBase() and the +/// motivation for the API, like calling AAD a "header", can be found in Bellare, +/// Rogaway and Wagner's The EAX +/// Mode of Operation. The EAX paper suggested a basic API to help standardize AEAD +/// schemes in software and promote adoption of the modes. +/// \sa Authenticated +/// Encryption on the Crypto++ wiki. +/// \since Crypto++ 5.6.0 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AuthenticatedSymmetricCipherBase : public AuthenticatedSymmetricCipher { public: diff --git a/base32.h b/base32.h index 7818a220..f3318495 100644 --- a/base32.h +++ b/base32.h @@ -1,8 +1,8 @@ // base32.h - written and placed in the public domain by Frank Palazzolo, based on hex.cpp by Wei Dai // extended hex alphabet added by JW in November, 2017. -//! \file base32.h -//! \brief Classes for Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder +/// \file base32.h +/// \brief Classes for Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder #ifndef CRYPTOPP_BASE32_H #define CRYPTOPP_BASE32_H @@ -12,148 +12,148 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Base32Encoder -//! \brief Base32 encodes data using DUDE encoding -//! \details Converts data to base32 using DUDE encoding. The default code is based on Differential Unicode Domain Encoding (DUDE) (draft-ietf-idn-dude-02.txt). -//! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder +/// \class Base32Encoder +/// \brief Base32 encodes data using DUDE encoding +/// \details Converts data to base32 using DUDE encoding. The default code is based on Differential Unicode Domain Encoding (DUDE) (draft-ietf-idn-dude-02.txt). +/// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder class Base32Encoder : public SimpleProxyFilter { public: - //! \brief Construct a Base32Encoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \param uppercase a flag indicating uppercase output - //! \param groupSize the size of the grouping - //! \param separator the separator to use between groups - //! \param terminator the terminator appeand after processing - //! \details Base32Encoder() constructs a default encoder. The constructor lacks fields for padding and - //! line breaks. You must use IsolatedInitialize() to change the default padding character or suppress it. - //! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder + /// \brief Construct a Base32Encoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \param uppercase a flag indicating uppercase output + /// \param groupSize the size of the grouping + /// \param separator the separator to use between groups + /// \param terminator the terminator appeand after processing + /// \details Base32Encoder() constructs a default encoder. The constructor lacks fields for padding and + /// line breaks. You must use IsolatedInitialize() to change the default padding character or suppress it. + /// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder Base32Encoder(BufferedTransformation *attachment = NULLPTR, bool uppercase = true, int groupSize = 0, const std::string &separator = ":", const std::string &terminator = "") : SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment) { IsolatedInitialize(MakeParameters(Name::Uppercase(), uppercase)(Name::GroupSize(), groupSize)(Name::Separator(), ConstByteArrayParameter(separator))(Name::Terminator(), ConstByteArrayParameter(terminator))); } - //! \brief Initialize or reinitialize this object, without signal propagation - //! \param parameters a set of NameValuePairs used to initialize this object - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached - //! transformations. If initialization should be propagated, then use the Initialize() function. - //! \details The following code modifies the padding and line break parameters for an encoder: - //! 
-	//!     Base32Encoder encoder;
-	//!     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);
-	//!     encoder.IsolatedInitialize(params);
- //! \details You can change the encoding to RFC 4648, Base - //! 32 Encoding with Extended Hex Alphabet by performing the following: - //! 
-	//!     Base32Encoder encoder;
-	//!     const byte ALPHABET[] = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
-	//!     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);
-	//!     encoder.IsolatedInitialize(params);
- //! \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and - //! the decoder's lookup table. - //! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder + /// \brief Initialize or reinitialize this object, without signal propagation + /// \param parameters a set of NameValuePairs used to initialize this object + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached + /// transformations. If initialization should be propagated, then use the Initialize() function. + /// \details The following code modifies the padding and line break parameters for an encoder: + /// 
+	///     Base32Encoder encoder;
+	///     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);
+	///     encoder.IsolatedInitialize(params);
+ /// \details You can change the encoding to RFC 4648, Base + /// 32 Encoding with Extended Hex Alphabet by performing the following: + /// 
+	///     Base32Encoder encoder;
+	///     const byte ALPHABET[] = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
+	///     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);
+	///     encoder.IsolatedInitialize(params);
+ /// \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and + /// the decoder's lookup table. + /// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder void IsolatedInitialize(const NameValuePairs ¶meters); }; -//! \class Base32Decoder -//! \brief Base32 decodes data using DUDE encoding -//! \details Converts data from base32 using DUDE encoding. The default code is based on Differential Unicode Domain Encoding (DUDE) (draft-ietf-idn-dude-02.txt). -//! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder +/// \class Base32Decoder +/// \brief Base32 decodes data using DUDE encoding +/// \details Converts data from base32 using DUDE encoding. The default code is based on Differential Unicode Domain Encoding (DUDE) (draft-ietf-idn-dude-02.txt). +/// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder class Base32Decoder : public BaseN_Decoder { public: - //! \brief Construct a Base32Decoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \sa IsolatedInitialize() for an example of modifying a Base32Decoder after construction. + /// \brief Construct a Base32Decoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \sa IsolatedInitialize() for an example of modifying a Base32Decoder after construction. Base32Decoder(BufferedTransformation *attachment = NULLPTR) : BaseN_Decoder(GetDefaultDecodingLookupArray(), 5, attachment) {} - //! \brief Initialize or reinitialize this object, without signal propagation - //! \param parameters a set of NameValuePairs used to initialize this object - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached - //! transformations. If initialization should be propagated, then use the Initialize() function. - //! \details You can change the encoding to RFC 4648, Base - //! 32 Encoding with Extended Hex Alphabet by performing the following: - //! 
-	//!     int lookup[256];
-	//!     const byte ALPHABET[] = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
-	//!     Base32Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 32, true /*insensitive*/);
-	//!
-	//!     Base32Decoder decoder;
-	//!     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);
-	//!     decoder.IsolatedInitialize(params);
- //! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder + /// \brief Initialize or reinitialize this object, without signal propagation + /// \param parameters a set of NameValuePairs used to initialize this object + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached + /// transformations. If initialization should be propagated, then use the Initialize() function. + /// \details You can change the encoding to RFC 4648, Base + /// 32 Encoding with Extended Hex Alphabet by performing the following: + /// 
+	///     int lookup[256];
+	///     const byte ALPHABET[] = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
+	///     Base32Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 32, true /*insensitive*/);
+	///
+	///     Base32Decoder decoder;
+	///     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);
+	///     decoder.IsolatedInitialize(params);
+ /// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder void IsolatedInitialize(const NameValuePairs ¶meters); private: - //! \brief Provides the default decoding lookup table - //! \return default decoding lookup table + /// \brief Provides the default decoding lookup table + /// \return default decoding lookup table static const int * CRYPTOPP_API GetDefaultDecodingLookupArray(); }; -//! \class Base32HexEncoder -//! \brief Base32 encodes data using extended hex -//! \details Converts data to base32 using extended hex alphabet. The alphabet is different than Base32Encoder. -//! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder, RFC 4648, Base 32 Encoding with Extended Hex Alphabet. -//! \since Crypto++ 6.0 +/// \class Base32HexEncoder +/// \brief Base32 encodes data using extended hex +/// \details Converts data to base32 using extended hex alphabet. The alphabet is different than Base32Encoder. +/// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder, RFC 4648, Base 32 Encoding with Extended Hex Alphabet. +/// \since Crypto++ 6.0 class Base32HexEncoder : public SimpleProxyFilter { public: - //! \brief Construct a Base32HexEncoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \param uppercase a flag indicating uppercase output - //! \param groupSize the size of the grouping - //! \param separator the separator to use between groups - //! \param terminator the terminator appeand after processing - //! \details Base32HexEncoder() constructs a default encoder. The constructor lacks fields for padding and - //! line breaks. You must use IsolatedInitialize() to change the default padding character or suppress it. - //! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder + /// \brief Construct a Base32HexEncoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \param uppercase a flag indicating uppercase output + /// \param groupSize the size of the grouping + /// \param separator the separator to use between groups + /// \param terminator the terminator appeand after processing + /// \details Base32HexEncoder() constructs a default encoder. The constructor lacks fields for padding and + /// line breaks. You must use IsolatedInitialize() to change the default padding character or suppress it. + /// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder Base32HexEncoder(BufferedTransformation *attachment = NULLPTR, bool uppercase = true, int groupSize = 0, const std::string &separator = ":", const std::string &terminator = "") : SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment) { IsolatedInitialize(MakeParameters(Name::Uppercase(), uppercase)(Name::GroupSize(), groupSize)(Name::Separator(), ConstByteArrayParameter(separator))(Name::Terminator(), ConstByteArrayParameter(terminator))); } - //! \brief Initialize or reinitialize this object, without signal propagation - //! \param parameters a set of NameValuePairs used to initialize this object - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached - //! transformations. If initialization should be propagated, then use the Initialize() function. - //! \details The following code modifies the padding and line break parameters for an encoder: - //! 
-	//!     Base32HexEncoder encoder;
-	//!     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);
-	//!     encoder.IsolatedInitialize(params);
+ /// \brief Initialize or reinitialize this object, without signal propagation + /// \param parameters a set of NameValuePairs used to initialize this object + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached + /// transformations. If initialization should be propagated, then use the Initialize() function. + /// \details The following code modifies the padding and line break parameters for an encoder: + /// 
+	///     Base32HexEncoder encoder;
+	///     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);
+	///     encoder.IsolatedInitialize(params);
void IsolatedInitialize(const NameValuePairs ¶meters); }; -//! \class Base32HexDecoder -//! \brief Base32 decodes data using extended hex -//! \details Converts data from base32 using extended hex alphabet. The alphabet is different than Base32Decoder. -//! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder, RFC 4648, Base 32 Encoding with Extended Hex Alphabet. -//! \since Crypto++ 6.0 +/// \class Base32HexDecoder +/// \brief Base32 decodes data using extended hex +/// \details Converts data from base32 using extended hex alphabet. The alphabet is different than Base32Decoder. +/// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder, RFC 4648, Base 32 Encoding with Extended Hex Alphabet. +/// \since Crypto++ 6.0 class Base32HexDecoder : public BaseN_Decoder { public: - //! \brief Construct a Base32HexDecoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder + /// \brief Construct a Base32HexDecoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \sa Base32Encoder, Base32Decoder, Base32HexEncoder and Base32HexDecoder Base32HexDecoder(BufferedTransformation *attachment = NULLPTR) : BaseN_Decoder(GetDefaultDecodingLookupArray(), 5, attachment) {} - //! \brief Initialize or reinitialize this object, without signal propagation - //! \param parameters a set of NameValuePairs used to initialize this object - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached - //! transformations. If initialization should be propagated, then use the Initialize() function. + /// \brief Initialize or reinitialize this object, without signal propagation + /// \param parameters a set of NameValuePairs used to initialize this object + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached + /// transformations. If initialization should be propagated, then use the Initialize() function. void IsolatedInitialize(const NameValuePairs ¶meters); private: - //! \brief Provides the default decoding lookup table - //! \return default decoding lookup table + /// \brief Provides the default decoding lookup table + /// \return default decoding lookup table static const int * CRYPTOPP_API GetDefaultDecodingLookupArray(); }; diff --git a/base64.h b/base64.h index 5213f89e..0fdcd21f 100644 --- a/base64.h +++ b/base64.h @@ -1,7 +1,7 @@ // base64.h - originally written and placed in the public domain by Wei Dai -//! \file base64.h -//! \brief Classes for the Base64Encoder, Base64Decoder, Base64URLEncoder and Base64URLDecoder +/// \file base64.h +/// \brief Classes for the Base64Encoder, Base64Decoder, Base64URLEncoder and Base64URLDecoder #ifndef CRYPTOPP_BASE64_H #define CRYPTOPP_BASE64_H @@ -11,104 +11,104 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Base64Encoder -//! \brief Base64 encodes data -//! \details Base64 encodes data per RFC 4648, Base 64 Encoding. +/// \class Base64Encoder +/// \brief Base64 encodes data +/// \details Base64 encodes data per RFC 4648, Base 64 Encoding. class Base64Encoder : public SimpleProxyFilter { public: - //! \brief Construct a Base64Encoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \param insertLineBreaks a BufferedTrasformation to attach to this object - //! \param maxLineLength the length of a line if line breaks are used - //! \details Base64Encoder constructs a default encoder. The constructor lacks a parameter for padding, and you must - //! use IsolatedInitialize() to modify the Base64Encoder after construction. - //! \sa IsolatedInitialize() for an example of modifying an encoder after construction. + /// \brief Construct a Base64Encoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \param insertLineBreaks a BufferedTrasformation to attach to this object + /// \param maxLineLength the length of a line if line breaks are used + /// \details Base64Encoder constructs a default encoder. The constructor lacks a parameter for padding, and you must + /// use IsolatedInitialize() to modify the Base64Encoder after construction. + /// \sa IsolatedInitialize() for an example of modifying an encoder after construction. Base64Encoder(BufferedTransformation *attachment = NULLPTR, bool insertLineBreaks = true, int maxLineLength = 72) : SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment) { IsolatedInitialize(MakeParameters(Name::InsertLineBreaks(), insertLineBreaks)(Name::MaxLineLength(), maxLineLength)); } - //! \brief Initialize or reinitialize this object, without signal propagation - //! \param parameters a set of NameValuePairs used to initialize this object - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached - //! transformations. If initialization should be propagated, then use the Initialize() function. - //! \details The following code modifies the padding and line break parameters for an encoder: - //! 
-	//!     Base64Encoder encoder;
-	//!     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);
-	//!     encoder.IsolatedInitialize(params);
- //! \details You can change the encoding to RFC 4648 web safe alphabet by performing the following: - //! 
-	//!     Base64Encoder encoder;
-	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-	//!     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);
-	//!     encoder.IsolatedInitialize(params);
- //! \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and - //! the decoder's lookup table. - //! \sa Base64URLEncoder for an encoder that provides the web safe alphabet, and Base64Decoder::IsolatedInitialize() - //! for an example of modifying a decoder's lookup table after construction. + /// \brief Initialize or reinitialize this object, without signal propagation + /// \param parameters a set of NameValuePairs used to initialize this object + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached + /// transformations. If initialization should be propagated, then use the Initialize() function. + /// \details The following code modifies the padding and line break parameters for an encoder: + /// 
+	///     Base64Encoder encoder;
+	///     AlgorithmParameters params = MakeParameters(Pad(), false)(InsertLineBreaks(), false);
+	///     encoder.IsolatedInitialize(params);
+ /// \details You can change the encoding to RFC 4648 web safe alphabet by performing the following: + /// 
+	///     Base64Encoder encoder;
+	///     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+	///     AlgorithmParameters params = MakeParameters(Name::EncodingLookupArray(),(const byte *)ALPHABET);
+	///     encoder.IsolatedInitialize(params);
+ /// \details If you change the encoding alphabet, then you will need to change the decoding alphabet \a and + /// the decoder's lookup table. + /// \sa Base64URLEncoder for an encoder that provides the web safe alphabet, and Base64Decoder::IsolatedInitialize() + /// for an example of modifying a decoder's lookup table after construction. void IsolatedInitialize(const NameValuePairs ¶meters); }; -//! \class Base64Decoder -//! \brief Base64 decodes data -//! \details Base64 encodes data per RFC 4648, Base 64 Encoding. +/// \class Base64Decoder +/// \brief Base64 decodes data +/// \details Base64 encodes data per RFC 4648, Base 64 Encoding. class Base64Decoder : public BaseN_Decoder { public: - //! \brief Construct a Base64Decoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \sa IsolatedInitialize() for an example of modifying an encoder after construction. + /// \brief Construct a Base64Decoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \sa IsolatedInitialize() for an example of modifying an encoder after construction. Base64Decoder(BufferedTransformation *attachment = NULLPTR) : BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {} - //! \brief Initialize or reinitialize this object, without signal propagation - //! \param parameters a set of NameValuePairs used to initialize this object - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached - //! transformations. If initialization should be propagated, then use the Initialize() function. - //! \details The default decoding alpahbet is RFC 4868. You can change the to RFC 4868 web safe alphabet - //! by performing the following: - //! 
-	//!     int lookup[256];
-	//!     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-	//!     Base64Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 64, false);
-	//!
-	//!     Base64Decoder decoder;
-	//!     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);
-	//!     decoder.IsolatedInitialize(params);
- //! \sa Base64URLDecoder for a decoder that provides the web safe alphabet, and Base64Encoder::IsolatedInitialize() - //! for an example of modifying an encoder's alphabet after construction. + /// \brief Initialize or reinitialize this object, without signal propagation + /// \param parameters a set of NameValuePairs used to initialize this object + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached + /// transformations. If initialization should be propagated, then use the Initialize() function. + /// \details The default decoding alpahbet is RFC 4868. You can change the to RFC 4868 web safe alphabet + /// by performing the following: + /// 
+	///     int lookup[256];
+	///     const byte ALPHABET[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+	///     Base64Decoder::InitializeDecodingLookupArray(lookup, ALPHABET, 64, false);
+	///
+	///     Base64Decoder decoder;
+	///     AlgorithmParameters params = MakeParameters(Name::DecodingLookupArray(),(const int *)lookup);
+	///     decoder.IsolatedInitialize(params);
+ /// \sa Base64URLDecoder for a decoder that provides the web safe alphabet, and Base64Encoder::IsolatedInitialize() + /// for an example of modifying an encoder's alphabet after construction. void IsolatedInitialize(const NameValuePairs ¶meters); private: - //! \brief Provides the default decoding lookup table - //! \return default decoding lookup table + /// \brief Provides the default decoding lookup table + /// \return default decoding lookup table static const int * CRYPTOPP_API GetDecodingLookupArray(); }; -//! \class Base64URLEncoder -//! \brief Base64 encodes data using a web safe alphabet -//! \details Base64 encodes data per RFC 4648, Base 64 Encoding -//! with URL and Filename Safe Alphabet. +/// \class Base64URLEncoder +/// \brief Base64 encodes data using a web safe alphabet +/// \details Base64 encodes data per RFC 4648, Base 64 Encoding +/// with URL and Filename Safe Alphabet. class Base64URLEncoder : public SimpleProxyFilter { public: - //! \brief Construct a Base64URLEncoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \param insertLineBreaks a BufferedTrasformation to attach to this object - //! \param maxLineLength the length of a line if line breaks are used - //! \details Base64URLEncoder() constructs a default encoder using a web safe alphabet. The constructor ignores - //! insertLineBreaks and maxLineLength because the web and URL safe specifications don't use them. They are - //! present in the constructor for API compatibility with Base64Encoder so it is a drop-in replacement. The - //! constructor also disables padding on the encoder for the same reason. - //! \details If you need line breaks or padding, then you must use IsolatedInitialize() to set them - //! after constructing a Base64URLEncoder. - //! \sa Base64Encoder for an encoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize - //! for an example of modifying an encoder after construction. + /// \brief Construct a Base64URLEncoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \param insertLineBreaks a BufferedTrasformation to attach to this object + /// \param maxLineLength the length of a line if line breaks are used + /// \details Base64URLEncoder() constructs a default encoder using a web safe alphabet. The constructor ignores + /// insertLineBreaks and maxLineLength because the web and URL safe specifications don't use them. They are + /// present in the constructor for API compatibility with Base64Encoder so it is a drop-in replacement. The + /// constructor also disables padding on the encoder for the same reason. + /// \details If you need line breaks or padding, then you must use IsolatedInitialize() to set them + /// after constructing a Base64URLEncoder. + /// \sa Base64Encoder for an encoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize + /// for an example of modifying an encoder after construction. Base64URLEncoder(BufferedTransformation *attachment = NULLPTR, bool insertLineBreaks = false, int maxLineLength = -1) : SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment) { @@ -116,44 +116,44 @@ public: IsolatedInitialize(MakeParameters(Name::InsertLineBreaks(), false)(Name::MaxLineLength(), -1)(Name::Pad(),false)); } - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached - //! transformations. If initialization should be propagated, then use the Initialize() function. - //! \details The following code modifies the padding and line break parameters for an encoder: - //! 
-	//!     Base64URLEncoder encoder;
-	//!     AlgorithmParameters params = MakeParameters(Name::Pad(), true)(Name::InsertLineBreaks(), true);
-	//!     encoder.IsolatedInitialize(params);
- //! \sa Base64Encoder for an encoder that provides a classic alphabet. + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on attached + /// transformations. If initialization should be propagated, then use the Initialize() function. + /// \details The following code modifies the padding and line break parameters for an encoder: + /// 
+	///     Base64URLEncoder encoder;
+	///     AlgorithmParameters params = MakeParameters(Name::Pad(), true)(Name::InsertLineBreaks(), true);
+	///     encoder.IsolatedInitialize(params);
+ /// \sa Base64Encoder for an encoder that provides a classic alphabet. void IsolatedInitialize(const NameValuePairs ¶meters); }; -//! \class Base64URLDecoder -//! \brief Base64 decodes data using a web safe alphabet -//! \details Base64 encodes data per RFC 4648, Base 64 Encoding -//! with URL and Filename Safe Alphabet. +/// \class Base64URLDecoder +/// \brief Base64 decodes data using a web safe alphabet +/// \details Base64 encodes data per RFC 4648, Base 64 Encoding +/// with URL and Filename Safe Alphabet. class Base64URLDecoder : public BaseN_Decoder { public: - //! \brief Construct a Base64URLDecoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \details Base64URLDecoder() constructs a default decoder using a web safe alphabet. - //! \sa Base64Decoder for a decoder that provides a classic alphabet. + /// \brief Construct a Base64URLDecoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \details Base64URLDecoder() constructs a default decoder using a web safe alphabet. + /// \sa Base64Decoder for a decoder that provides a classic alphabet. Base64URLDecoder(BufferedTransformation *attachment = NULLPTR) : BaseN_Decoder(GetDecodingLookupArray(), 6, attachment) {} - //! \brief Initialize or reinitialize this object, without signal propagation - //! \param parameters a set of NameValuePairs used to initialize this object - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on - //! attached transformations. If initialization should be propagated, then use the Initialize() function. - //! \sa Base64Decoder for a decoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize - //! for an example of modifying an encoder after construction. + /// \brief Initialize or reinitialize this object, without signal propagation + /// \param parameters a set of NameValuePairs used to initialize this object + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. IsolatedInitialize() does not call Initialize() on + /// attached transformations. If initialization should be propagated, then use the Initialize() function. + /// \sa Base64Decoder for a decoder that provides a classic alphabet, and Base64URLEncoder::IsolatedInitialize + /// for an example of modifying an encoder after construction. void IsolatedInitialize(const NameValuePairs ¶meters); private: - //! \brief Provides the default decoding lookup table - //! \return default decoding lookup table + /// \brief Provides the default decoding lookup table + /// \return default decoding lookup table static const int * CRYPTOPP_API GetDecodingLookupArray(); }; diff --git a/basecode.h b/basecode.h index a522d6db..1eaaae6e 100644 --- a/basecode.h +++ b/basecode.h @@ -1,7 +1,7 @@ // basecode.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \brief Base classes for working with encoders and decoders. +/// \file +/// \brief Base classes for working with encoders and decoders. #ifndef CRYPTOPP_BASECODE_H #define CRYPTOPP_BASECODE_H @@ -13,25 +13,25 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class BaseN_Encoder -//! \brief Encoder for bases that are a power of 2 +/// \class BaseN_Encoder +/// \brief Encoder for bases that are a power of 2 class CRYPTOPP_DLL BaseN_Encoder : public Unflushable { public: - //! \brief Construct a BaseN_Encoder - //! \param attachment a BufferedTransformation to attach to this object + /// \brief Construct a BaseN_Encoder + /// \param attachment a BufferedTransformation to attach to this object BaseN_Encoder(BufferedTransformation *attachment=NULLPTR) : m_alphabet(NULLPTR), m_padding(0), m_bitsPerChar(0) , m_outputBlockSize(0), m_bytePos(0), m_bitPos(0) {Detach(attachment);} - //! \brief Construct a BaseN_Encoder - //! \param alphabet table of ASCII characters to use as the alphabet - //! \param log2base the log2base - //! \param attachment a BufferedTransformation to attach to this object - //! \param padding the character to use as padding - //! \pre log2base must be between 1 and 7 inclusive - //! \throws InvalidArgument if log2base is not between 1 and 7 + /// \brief Construct a BaseN_Encoder + /// \param alphabet table of ASCII characters to use as the alphabet + /// \param log2base the log2base + /// \param attachment a BufferedTransformation to attach to this object + /// \param padding the character to use as padding + /// \pre log2base must be between 1 and 7 inclusive + /// \throws InvalidArgument if log2base is not between 1 and 7 BaseN_Encoder(const byte *alphabet, int log2base, BufferedTransformation *attachment=NULLPTR, int padding=-1) : m_alphabet(NULLPTR), m_padding(0), m_bitsPerChar(0) , m_outputBlockSize(0), m_bytePos(0), m_bitPos(0) @@ -53,28 +53,28 @@ private: SecByteBlock m_outBuf; }; -//! \class BaseN_Decoder -//! \brief Decoder for bases that are a power of 2 +/// \class BaseN_Decoder +/// \brief Decoder for bases that are a power of 2 class CRYPTOPP_DLL BaseN_Decoder : public Unflushable { public: - //! \brief Construct a BaseN_Decoder - //! \param attachment a BufferedTransformation to attach to this object - //! \details padding is set to -1, which means use default padding. If not - //! required, then the value must be set via IsolatedInitialize(). + /// \brief Construct a BaseN_Decoder + /// \param attachment a BufferedTransformation to attach to this object + /// \details padding is set to -1, which means use default padding. If not + /// required, then the value must be set via IsolatedInitialize(). BaseN_Decoder(BufferedTransformation *attachment=NULLPTR) : m_lookup(NULLPTR), m_padding(0), m_bitsPerChar(0) , m_outputBlockSize(0), m_bytePos(0), m_bitPos(0) {Detach(attachment);} - //! \brief Construct a BaseN_Decoder - //! \param lookup table of values - //! \param log2base the log2base - //! \param attachment a BufferedTransformation to attach to this object - //! \details log2base is the exponent (like 5 in 25), and not - //! the number of elements (like 32). - //! \details padding is set to -1, which means use default padding. If not - //! required, then the value must be set via IsolatedInitialize(). + /// \brief Construct a BaseN_Decoder + /// \param lookup table of values + /// \param log2base the log2base + /// \param attachment a BufferedTransformation to attach to this object + /// \details log2base is the exponent (like 5 in 25), and not + /// the number of elements (like 32). + /// \details padding is set to -1, which means use default padding. If not + /// required, then the value must be set via IsolatedInitialize(). BaseN_Decoder(const int *lookup, int log2base, BufferedTransformation *attachment=NULLPTR) : m_lookup(NULLPTR), m_padding(0), m_bitsPerChar(0) , m_outputBlockSize(0), m_bytePos(0), m_bitPos(0) @@ -86,16 +86,16 @@ public: void IsolatedInitialize(const NameValuePairs ¶meters); size_t Put2(const byte *begin, size_t length, int messageEnd, bool blocking); - //! \brief Initializes BaseN lookup array - //! \param lookup table of values - //! \param alphabet table of ASCII characters - //! \param base the base for the encoder - //! \param caseInsensitive flag indicating whether the alphabet is case sensitivie - //! \pre COUNTOF(lookup) == 256 - //! \pre COUNTOF(alphabet) == base - //! \details Internally, the function sets the first 256 elements in the lookup table to - //! their value from the alphabet array or -1. base is the number of element (like 32), - //! and not an exponent (like 5 in 25) + /// \brief Initializes BaseN lookup array + /// \param lookup table of values + /// \param alphabet table of ASCII characters + /// \param base the base for the encoder + /// \param caseInsensitive flag indicating whether the alphabet is case sensitivie + /// \pre COUNTOF(lookup) == 256 + /// \pre COUNTOF(alphabet) == base + /// \details Internally, the function sets the first 256 elements in the lookup table to + /// their value from the alphabet array or -1. base is the number of element (like 32), + /// and not an exponent (like 5 in 25) static void CRYPTOPP_API InitializeDecodingLookupArray(int *lookup, const byte *alphabet, unsigned int base, bool caseInsensitive); private: @@ -105,21 +105,21 @@ private: SecByteBlock m_outBuf; }; -//! \class Grouper -//! \brief Filter that breaks input stream into groups of fixed size +/// \class Grouper +/// \brief Filter that breaks input stream into groups of fixed size class CRYPTOPP_DLL Grouper : public Bufferless { public: - //! \brief Construct a Grouper - //! \param attachment a BufferedTransformation to attach to this object + /// \brief Construct a Grouper + /// \param attachment a BufferedTransformation to attach to this object Grouper(BufferedTransformation *attachment=NULLPTR) : m_groupSize(0), m_counter(0) {Detach(attachment);} - //! \brief Construct a Grouper - //! \param groupSize the size of the grouping - //! \param separator the separator to use between groups - //! \param terminator the terminator appeand after processing - //! \param attachment a BufferedTransformation to attach to this object + /// \brief Construct a Grouper + /// \param groupSize the size of the grouping + /// \param separator the separator to use between groups + /// \param terminator the terminator appeand after processing + /// \param attachment a BufferedTransformation to attach to this object Grouper(int groupSize, const std::string &separator, const std::string &terminator, BufferedTransformation *attachment=NULLPTR) : m_groupSize(0), m_counter(0) { diff --git a/blake2.h b/blake2.h index b3402001..2e575f93 100644 --- a/blake2.h +++ b/blake2.h @@ -2,17 +2,17 @@ // Wilcox-O'Hearn. Based on Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's // reference BLAKE2 implementation at http://github.com/BLAKE2/BLAKE2. -//! \file blake2.h -//! \brief Classes for BLAKE2b and BLAKE2s message digests and keyed message digests -//! \details This implementation follows Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's -//! BLAKE2: simpler, smaller, fast as MD5 (2013.01.29). -//! Static algorithm name return either "BLAKE2b" or "BLAKE2s". An object algorithm name follows -//! the naming described in RFC 7693, The -//! BLAKE2 Cryptographic Hash and Message Authentication Code (MAC). -//! \details The library provides specialized SSE2, SSE4 and NEON version of the BLAKE2 compression -//! function. For best results under ARM NEON, specify both an architecture and cpu. For example: -//! 
CXXFLAGS="-DNDEBUG -march=armv8-a+crc -mcpu=cortex-a53 ..."
-//! \since Crypto++ 5.6.4 +/// \file blake2.h +/// \brief Classes for BLAKE2b and BLAKE2s message digests and keyed message digests +/// \details This implementation follows Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's +/// BLAKE2: simpler, smaller, fast as MD5 (2013.01.29). +/// Static algorithm name return either "BLAKE2b" or "BLAKE2s". An object algorithm name follows +/// the naming described in RFC 7693, The +/// BLAKE2 Cryptographic Hash and Message Authentication Code (MAC). +/// \details The library provides specialized SSE2, SSE4 and NEON version of the BLAKE2 compression +/// function. For best results under ARM NEON, specify both an architecture and cpu. For example: +/// 
CXXFLAGS="-DNDEBUG -march=armv8-a+crc -mcpu=cortex-a53 ..."
+/// \since Crypto++ 5.6.4 #ifndef CRYPTOPP_BLAKE2_H #define CRYPTOPP_BLAKE2_H @@ -23,10 +23,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class BLAKE2_Info -//! \brief BLAKE2 hash information -//! \tparam T_64bit flag indicating 64-bit -//! \since Crypto++ 5.6.4 +/// \class BLAKE2_Info +/// \brief BLAKE2 hash information +/// \tparam T_64bit flag indicating 64-bit +/// \since Crypto++ 5.6.4 template struct BLAKE2_Info : public VariableKeyLength<(T_64bit ? 64 : 32),0,(T_64bit ? 64 : 32),1,SimpleKeyingInterface::NOT_RESYNCHRONIZABLE> { @@ -43,18 +43,18 @@ struct BLAKE2_Info : public VariableKeyLength<(T_64bit ? 64 : 32),0,(T_64bit ? 6 CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return (T_64bit ? "BLAKE2b" : "BLAKE2s");} }; -//! \class BLAKE2_ParameterBlock -//! \brief BLAKE2 parameter block -//! \tparam T_64bit flag indicating 64-bit -//! \details BLAKE2b uses BLAKE2_ParameterBlock, while BLAKE2s -//! uses BLAKE2_ParameterBlock. -//! \since Crypto++ 5.6.4 +/// \class BLAKE2_ParameterBlock +/// \brief BLAKE2 parameter block +/// \tparam T_64bit flag indicating 64-bit +/// \details BLAKE2b uses BLAKE2_ParameterBlock, while BLAKE2s +/// uses BLAKE2_ParameterBlock. +/// \since Crypto++ 5.6.4 template struct CRYPTOPP_NO_VTABLE BLAKE2_ParameterBlock { }; -//! \brief BLAKE2b parameter block specialization +/// \brief BLAKE2b parameter block specialization template<> struct CRYPTOPP_NO_VTABLE BLAKE2_ParameterBlock { @@ -89,7 +89,7 @@ struct CRYPTOPP_NO_VTABLE BLAKE2_ParameterBlock byte personalization[PERSONALIZATIONSIZE]; }; -//! \brief BLAKE2s parameter block specialization +/// \brief BLAKE2s parameter block specialization template<> struct CRYPTOPP_NO_VTABLE BLAKE2_ParameterBlock { @@ -124,13 +124,13 @@ struct CRYPTOPP_NO_VTABLE BLAKE2_ParameterBlock byte personalization[PERSONALIZATIONSIZE]; }; -//! \class BLAKE2_State -//! \brief BLAKE2 state information -//! \tparam W word type -//! \tparam T_64bit flag indicating 64-bit -//! \details BLAKE2b uses BLAKE2_State, while BLAKE2s -//! uses BLAKE2_State. -//! \since Crypto++ 5.6.4 +/// \class BLAKE2_State +/// \brief BLAKE2 state information +/// \tparam W word type +/// \tparam T_64bit flag indicating 64-bit +/// \details BLAKE2b uses BLAKE2_State, while BLAKE2s +/// uses BLAKE2_State. +/// \since Crypto++ 5.6.4 template struct CRYPTOPP_NO_VTABLE BLAKE2_State { @@ -150,13 +150,13 @@ struct CRYPTOPP_NO_VTABLE BLAKE2_State size_t length; }; -//! \class BLAKE2_Base -//! \brief BLAKE2 hash implementation -//! \tparam W word type -//! \tparam T_64bit flag indicating 64-bit -//! \details BLAKE2b uses BLAKE2_Base, while BLAKE2s -//! uses BLAKE2_Base. -//! \since Crypto++ 5.6.4 +/// \class BLAKE2_Base +/// \brief BLAKE2 hash implementation +/// \tparam W word type +/// \tparam T_64bit flag indicating 64-bit +/// \details BLAKE2b uses BLAKE2_Base, while BLAKE2s +/// uses BLAKE2_Base. +/// \since Crypto++ 5.6.4 template class BLAKE2_Base : public SimpleKeyingInterfaceImpl > { @@ -177,15 +177,15 @@ public: virtual ~BLAKE2_Base() {} - //! \brief Retrieve the static algorithm name - //! \returns the algorithm name (BLAKE2s or BLAKE2b) + /// \brief Retrieve the static algorithm name + /// \returns the algorithm name (BLAKE2s or BLAKE2b) CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return BLAKE2_Info::StaticAlgorithmName();} - //! \brief Retrieve the object's name - //! \returns the object's algorithm name following RFC 7693 - //! \details Object algorithm name follows the naming described in - //! RFC 7693, The BLAKE2 Cryptographic Hash and - //! Message Authentication Code (MAC). For example, "BLAKE2b-512" and "BLAKE2s-256". + /// \brief Retrieve the object's name + /// \returns the object's algorithm name following RFC 7693 + /// \details Object algorithm name follows the naming described in + /// RFC 7693, The BLAKE2 Cryptographic Hash and + /// Message Authentication Code (MAC). For example, "BLAKE2b-512" and "BLAKE2s-256". std::string AlgorithmName() const {return std::string(StaticAlgorithmName()) + "-" + IntToString(this->DigestSize()*8);} unsigned int DigestSize() const {return m_digestSize;} @@ -194,23 +194,23 @@ public: void Update(const byte *input, size_t length); void Restart(); - //! \brief Restart a hash with parameter block and counter - //! \param block parameter block - //! \param counter counter array - //! \details Parameter block is persisted across calls to Restart(). + /// \brief Restart a hash with parameter block and counter + /// \param block parameter block + /// \param counter counter array + /// \details Parameter block is persisted across calls to Restart(). void Restart(const BLAKE2_ParameterBlock& block, const W counter[2]); - //! \brief Set tree mode - //! \param mode the new tree mode - //! \details BLAKE2 has two finalization flags, called State::f[0] and State::f[1]. - //! If treeMode=false (default), then State::f[1] is never set. If - //! treeMode=true, then State::f[1] is set when State::f[0] is set. - //! Tree mode is persisted across calls to Restart(). + /// \brief Set tree mode + /// \param mode the new tree mode + /// \details BLAKE2 has two finalization flags, called State::f[0] and State::f[1]. + /// If treeMode=false (default), then State::f[1] is never set. If + /// treeMode=true, then State::f[1] is set when State::f[0] is set. + /// Tree mode is persisted across calls to Restart(). void SetTreeMode(bool mode) {m_treeMode=mode;} - //! \brief Get tree mode - //! \returns the current tree mode - //! \details Tree mode is persisted across calls to Restart(). + /// \brief Get tree mode + /// \returns the current tree mode + /// \details Tree mode is persisted across calls to Restart(). bool GetTreeMode() const {return m_treeMode;} void TruncatedFinal(byte *hash, size_t size); @@ -236,15 +236,15 @@ private: bool m_treeMode; }; -//! \brief The BLAKE2b cryptographic hash function -//! \details BLAKE2b can function as both a hash and keyed hash. If you want only the hash, -//! then use the BLAKE2b constructor that accepts no parameters or digest size. If you -//! want a keyed hash, then use the constructor that accpts the key as a parameter. -//! Once a key and digest size are selected, its effectively immutable. The Restart() -//! method that accepts a ParameterBlock does not allow you to change it. -//! \sa Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's -//! BLAKE2: simpler, smaller, fast as MD5 (2013.01.29). -//! \since Crypto++ 5.6.4 +/// \brief The BLAKE2b cryptographic hash function +/// \details BLAKE2b can function as both a hash and keyed hash. If you want only the hash, +/// then use the BLAKE2b constructor that accepts no parameters or digest size. If you +/// want a keyed hash, then use the constructor that accpts the key as a parameter. +/// Once a key and digest size are selected, its effectively immutable. The Restart() +/// method that accepts a ParameterBlock does not allow you to change it. +/// \sa Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's +/// BLAKE2: simpler, smaller, fast as MD5 (2013.01.29). +/// \since Crypto++ 5.6.4 class BLAKE2b : public BLAKE2_Base { public: @@ -252,35 +252,35 @@ public: typedef BLAKE2_ParameterBlock ParameterBlock; CRYPTOPP_COMPILE_ASSERT(sizeof(ParameterBlock) == 64); - //! \brief Construct a BLAKE2b hash - //! \param digestSize the digest size, in bytes - //! \param treeMode flag indicating tree mode + /// \brief Construct a BLAKE2b hash + /// \param digestSize the digest size, in bytes + /// \param treeMode flag indicating tree mode BLAKE2b(bool treeMode=false, unsigned int digestSize = DIGESTSIZE) : ThisBase(treeMode, digestSize) {} - //! \brief Construct a BLAKE2b hash - //! \param key a byte array used to key the cipher - //! \param keyLength the size of the byte array - //! \param salt a byte array used as salt - //! \param saltLength the size of the byte array - //! \param personalization a byte array used as prsonalization string - //! \param personalizationLength the size of the byte array - //! \param treeMode flag indicating tree mode - //! \param digestSize the digest size, in bytes + /// \brief Construct a BLAKE2b hash + /// \param key a byte array used to key the cipher + /// \param keyLength the size of the byte array + /// \param salt a byte array used as salt + /// \param saltLength the size of the byte array + /// \param personalization a byte array used as prsonalization string + /// \param personalizationLength the size of the byte array + /// \param treeMode flag indicating tree mode + /// \param digestSize the digest size, in bytes BLAKE2b(const byte *key, size_t keyLength, const byte* salt = NULLPTR, size_t saltLength = 0, const byte* personalization = NULLPTR, size_t personalizationLength = 0, bool treeMode=false, unsigned int digestSize = DIGESTSIZE) : ThisBase(key, keyLength, salt, saltLength, personalization, personalizationLength, treeMode, digestSize) {} }; -//! \brief The BLAKE2s cryptographic hash function -//! \details BLAKE2s can function as both a hash and keyed hash. If you want only the hash, -//! then use the BLAKE2s constructor that accepts no parameters or digest size. If you -//! want a keyed hash, then use the constructor that accpts the key as a parameter. -//! Once a key and digest size are selected, its effectively immutable. The Restart() -//! method that accepts a ParameterBlock does not allow you to change it. -//! \sa Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's -//! BLAKE2: simpler, smaller, fast as MD5 (2013.01.29). -//! \since Crypto++ 5.6.4 +/// \brief The BLAKE2s cryptographic hash function +/// \details BLAKE2s can function as both a hash and keyed hash. If you want only the hash, +/// then use the BLAKE2s constructor that accepts no parameters or digest size. If you +/// want a keyed hash, then use the constructor that accpts the key as a parameter. +/// Once a key and digest size are selected, its effectively immutable. The Restart() +/// method that accepts a ParameterBlock does not allow you to change it. +/// \sa Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's +/// BLAKE2: simpler, smaller, fast as MD5 (2013.01.29). +/// \since Crypto++ 5.6.4 class BLAKE2s : public BLAKE2_Base { public: @@ -288,20 +288,20 @@ public: typedef BLAKE2_ParameterBlock ParameterBlock; CRYPTOPP_COMPILE_ASSERT(sizeof(ParameterBlock) == 32); - //! \brief Construct a BLAKE2s hash - //! \param digestSize the digest size, in bytes - //! \param treeMode flag indicating tree mode + /// \brief Construct a BLAKE2s hash + /// \param digestSize the digest size, in bytes + /// \param treeMode flag indicating tree mode BLAKE2s(bool treeMode=false, unsigned int digestSize = DIGESTSIZE) : ThisBase(treeMode, digestSize) {} - //! \brief Construct a BLAKE2s hash - //! \param key a byte array used to key the cipher - //! \param keyLength the size of the byte array - //! \param salt a byte array used as salt - //! \param saltLength the size of the byte array - //! \param personalization a byte array used as prsonalization string - //! \param personalizationLength the size of the byte array - //! \param treeMode flag indicating tree mode - //! \param digestSize the digest size, in bytes + /// \brief Construct a BLAKE2s hash + /// \param key a byte array used to key the cipher + /// \param keyLength the size of the byte array + /// \param salt a byte array used as salt + /// \param saltLength the size of the byte array + /// \param personalization a byte array used as prsonalization string + /// \param personalizationLength the size of the byte array + /// \param treeMode flag indicating tree mode + /// \param digestSize the digest size, in bytes BLAKE2s(const byte *key, size_t keyLength, const byte* salt = NULLPTR, size_t saltLength = 0, const byte* personalization = NULLPTR, size_t personalizationLength = 0, bool treeMode=false, unsigned int digestSize = DIGESTSIZE) diff --git a/blowfish.h b/blowfish.h index fa710149..fb2a772a 100644 --- a/blowfish.h +++ b/blowfish.h @@ -1,7 +1,7 @@ // blowfish.h - originally written and placed in the public domain by Wei Dai -//! \file blowfish.h -//! \brief Classes for the Blowfish block cipher +/// \file blowfish.h +/// \brief Classes for the Blowfish block cipher #ifndef CRYPTOPP_BLOWFISH_H #define CRYPTOPP_BLOWFISH_H @@ -11,8 +11,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Blowfish_Info -//! \brief Blowfish block cipher information +/// \class Blowfish_Info +/// \brief Blowfish block cipher information struct Blowfish_Info : public FixedBlockSize<8>, public VariableKeyLength<16, 4, 56>, public FixedRounds<16> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "Blowfish";} @@ -20,14 +20,14 @@ struct Blowfish_Info : public FixedBlockSize<8>, public VariableKeyLength<16, 4, // Blowfish -//! \class Blowfish -//! \brief Blowfish block cipher -//! \since Crypto++ 1.0 +/// \class Blowfish +/// \brief Blowfish block cipher +/// \since Crypto++ 1.0 class Blowfish : public Blowfish_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief Class specific implementation and overrides used to operate the cipher. - //! \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions + /// \class Base + /// \brief Class specific implementation and overrides used to operate the cipher. + /// \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: diff --git a/blumshub.h b/blumshub.h index 54fbc0f0..1827f47b 100644 --- a/blumshub.h +++ b/blumshub.h @@ -1,8 +1,8 @@ // blumshub.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile blumshub.h -//! \brief Classes for Blum Blum Shub generator +/// \file +/// \headerfile blumshub.h +/// \brief Classes for Blum Blum Shub generator #ifndef CRYPTOPP_BLUMSHUB_H #define CRYPTOPP_BLUMSHUB_H @@ -13,7 +13,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! BlumBlumShub without factorization of the modulus +/// BlumBlumShub without factorization of the modulus class PublicBlumBlumShub : public RandomNumberGenerator, public StreamTransformation { @@ -36,7 +36,7 @@ protected: word maxBits, bitsLeft; }; -//! BlumBlumShub with factorization of the modulus +/// BlumBlumShub with factorization of the modulus class BlumBlumShub : public PublicBlumBlumShub { public: diff --git a/camellia.h b/camellia.h index 1fa56e16..d29f9c56 100644 --- a/camellia.h +++ b/camellia.h @@ -1,7 +1,7 @@ // camellia.h - originally written and placed in the public domain by Wei Dai -//! \file camellia.h -//! \brief Classes for the Camellia block cipher +/// \file camellia.h +/// \brief Classes for the Camellia block cipher #ifndef CRYPTOPP_CAMELLIA_H #define CRYPTOPP_CAMELLIA_H @@ -12,16 +12,16 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Camellia_Info -//! \brief Camellia block cipher information +/// \class Camellia_Info +/// \brief Camellia block cipher information struct Camellia_Info : public FixedBlockSize<16>, public VariableKeyLength<16, 16, 32, 8> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "Camellia";} }; -//! \class Camellia -//! \brief Camellia block cipher -//! \sa Camellia +/// \class Camellia +/// \brief Camellia block cipher +/// \sa Camellia class Camellia : public Camellia_Info, public BlockCipherDocumentation { class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl diff --git a/cast.h b/cast.h index 99436c2e..89e66362 100644 --- a/cast.h +++ b/cast.h @@ -1,7 +1,7 @@ // cast.h - originally written and placed in the public domain by Wei Dai -//! \file cast.h -//! \brief Classes for the CAST-128 and CAST-256 block ciphers +/// \file cast.h +/// \brief Classes for the CAST-128 and CAST-256 block ciphers #ifndef CRYPTOPP_CAST_H #define CRYPTOPP_CAST_H @@ -11,28 +11,28 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class CAST -//! \brief CAST block cipher base +/// \class CAST +/// \brief CAST block cipher base class CAST { protected: static const word32 S[8][256]; }; -//! \class CAST128_Info -//! \brief CAST128 block cipher information +/// \class CAST128_Info +/// \brief CAST128 block cipher information struct CAST128_Info : public FixedBlockSize<8>, public VariableKeyLength<16, 5, 16> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "CAST-128";} }; -//! \class CAST128 -//! \brief CAST128 block cipher -//! \sa CAST-128 +/// \class CAST128 +/// \brief CAST128 block cipher +/// \sa CAST-128 class CAST128 : public CAST128_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief CAST128 block cipher default operation + /// \class Base + /// \brief CAST128 block cipher default operation class CRYPTOPP_NO_VTABLE Base : public CAST, public BlockCipherImpl { public: @@ -43,16 +43,16 @@ class CAST128 : public CAST128_Info, public BlockCipherDocumentation FixedSizeSecBlock K; }; - //! \class Enc - //! \brief CAST128 block cipher encryption operation + /// \class Enc + /// \brief CAST128 block cipher encryption operation class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \class Dec - //! \brief CAST128 block cipher decryption operation + /// \class Dec + /// \brief CAST128 block cipher decryption operation class CRYPTOPP_NO_VTABLE Dec : public Base { public: @@ -64,20 +64,20 @@ public: typedef BlockCipherFinal Decryption; }; -//! \class CAST256_Info -//! \brief CAST256 block cipher information +/// \class CAST256_Info +/// \brief CAST256 block cipher information struct CAST256_Info : public FixedBlockSize<16>, public VariableKeyLength<16, 16, 32, 4> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "CAST-256";} }; -//! \class CAST256 -//! \brief CAST256 block cipher -//! \sa CAST-256 +/// \class CAST256 +/// \brief CAST256 block cipher +/// \sa CAST-256 class CAST256 : public CAST256_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief CAST256 block cipher default operation + /// \class Base + /// \brief CAST256 block cipher default operation class CRYPTOPP_NO_VTABLE Base : public CAST, public BlockCipherImpl { public: diff --git a/cbcmac.h b/cbcmac.h index 985a34d1..2e0a4037 100644 --- a/cbcmac.h +++ b/cbcmac.h @@ -1,8 +1,8 @@ // cbcmac.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile cbcmac.h -//! \brief Classes for CBC MAC +/// \file +/// \headerfile cbcmac.h +/// \brief Classes for CBC MAC #ifndef CRYPTOPP_CBCMAC_H #define CRYPTOPP_CBCMAC_H @@ -12,7 +12,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! _ +/// _ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CBC_MAC_Base : public MessageAuthenticationCode { public: @@ -32,7 +32,7 @@ private: unsigned int m_counter; }; -//! CBC-MAC +/// CBC-MAC /*! Compatible with FIPS 113. T should be a class derived from BlockCipherDocumentation. Secure only for fixed length messages. For variable length messages use CMAC or DMAC. */ diff --git a/ccm.h b/ccm.h index c147f1af..398da200 100644 --- a/ccm.h +++ b/ccm.h @@ -1,8 +1,8 @@ // ccm.h - originally written and placed in the public domain by Wei Dai -//! \file ccm.h -//! \brief CCM block cipher mode of operation -//! \since Crypto++ 5.6.0 +/// \file ccm.h +/// \brief CCM block cipher mode of operation +/// \since Crypto++ 5.6.0 #ifndef CRYPTOPP_CCM_H #define CRYPTOPP_CCM_H @@ -12,10 +12,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class CCM_Base -//! \brief CCM block cipher base implementation -//! \details Base implementation of the AuthenticatedSymmetricCipher interface -//! \since Crypto++ 5.6.0 +/// \class CCM_Base +/// \brief CCM block cipher base implementation +/// \details Base implementation of the AuthenticatedSymmetricCipher interface +/// \since Crypto++ 5.6.0 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CCM_Base : public AuthenticatedSymmetricCipherBase { public: @@ -81,12 +81,12 @@ protected: CTR_Mode_ExternalCipher::Encryption m_ctr; }; -//! \class CCM_Final -//! \brief CCM block cipher final implementation -//! \tparam T_BlockCipher block cipher -//! \tparam T_DefaultDigestSize default digest size, in bytes -//! \tparam T_IsEncryption direction in which to operate the cipher -//! \since Crypto++ 5.6.0 +/// \class CCM_Final +/// \brief CCM block cipher final implementation +/// \tparam T_BlockCipher block cipher +/// \tparam T_DefaultDigestSize default digest size, in bytes +/// \tparam T_IsEncryption direction in which to operate the cipher +/// \since Crypto++ 5.6.0 template class CCM_Final : public CCM_Base { @@ -102,16 +102,16 @@ private: typename T_BlockCipher::Encryption m_cipher; }; -//! \class CCM -//! \brief CCM block cipher mode of operation -//! \tparam T_BlockCipher block cipher -//! \tparam T_DefaultDigestSize default digest size, in bytes -//! \details \p CCM provides the \p Encryption and \p Decryption typedef. See GCM_Base -//! and GCM_Final for the AuthenticatedSymmetricCipher implementation. -//! \sa CCM Mode and -//! Modes of Operation -//! on the Crypto++ wiki. -//! \since Crypto++ 5.6.0 +/// \class CCM +/// \brief CCM block cipher mode of operation +/// \tparam T_BlockCipher block cipher +/// \tparam T_DefaultDigestSize default digest size, in bytes +/// \details \p CCM provides the \p Encryption and \p Decryption typedef. See GCM_Base +/// and GCM_Final for the AuthenticatedSymmetricCipher implementation. +/// \sa CCM Mode and +/// Modes of Operation +/// on the Crypto++ wiki. +/// \since Crypto++ 5.6.0 template struct CCM : public AuthenticatedSymmetricCipherDocumentation { diff --git a/chacha.h b/chacha.h index b07031b7..12547380 100644 --- a/chacha.h +++ b/chacha.h @@ -2,13 +2,13 @@ // Based on Wei Dai's Salsa20 and Bernstein's reference ChaCha // family implementation at http://cr.yp.to/chacha.html. -//! \file chacha.h -//! \brief Classes for ChaCha8, ChaCha12 and ChaCha20 stream ciphers -//! \details Crypto++ provides Bernstein and ECRYPT's ChaCha from ChaCha, -//! a variant of Salsa20 (2008.01.28). Bernstein's implementation is _slightly_ different from the TLS working group's -//! implementation for cipher suites TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, -//! TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, and TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256. -//! \since Crypto++ 5.6.4 +/// \file chacha.h +/// \brief Classes for ChaCha8, ChaCha12 and ChaCha20 stream ciphers +/// \details Crypto++ provides Bernstein and ECRYPT's ChaCha from ChaCha, +/// a variant of Salsa20 (2008.01.28). Bernstein's implementation is _slightly_ different from the TLS working group's +/// implementation for cipher suites TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, +/// TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, and TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256. +/// \since Crypto++ 5.6.4 #ifndef CRYPTOPP_CHACHA_H #define CRYPTOPP_CHACHA_H @@ -18,9 +18,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ChaCha_Info -//! \brief ChaCha stream cipher information -//! \since Crypto++ 5.6.4 +/// \class ChaCha_Info +/// \brief ChaCha stream cipher information +/// \since Crypto++ 5.6.4 template struct ChaCha_Info : public VariableKeyLength<32, 16, 32, 16, SimpleKeyingInterface::UNIQUE_IV, 8>, public FixedRounds { @@ -29,9 +29,9 @@ struct ChaCha_Info : public VariableKeyLength<32, 16, 32, 16, SimpleKeyingInterf } }; -//! \class ChaCha_Policy -//! \brief ChaCha stream cipher implementation -//! \since Crypto++ 5.6.4 +/// \class ChaCha_Policy +/// \brief ChaCha stream cipher implementation +/// \since Crypto++ 5.6.4 template class CRYPTOPP_NO_VTABLE ChaCha_Policy : public AdditiveCipherConcretePolicy { @@ -49,36 +49,36 @@ protected: FixedSizeAlignedSecBlock m_state; }; -//! \class ChaCha8 -//! \brief ChaCha8 stream cipher -//! \sa ChaCha, a variant of Salsa20 (2008.01.28). -//! \since Crypto++ 5.6.4 +/// \class ChaCha8 +/// \brief ChaCha8 stream cipher +/// \sa ChaCha, a variant of Salsa20 (2008.01.28). +/// \since Crypto++ 5.6.4 struct ChaCha8 : public ChaCha_Info<8>, public SymmetricCipherDocumentation { typedef SymmetricCipherFinal, AdditiveCipherTemplate<> >, ChaCha_Info<8> > Encryption; typedef Encryption Decryption; }; -//! \class ChaCha12 -//! \brief ChaCha12 stream cipher -//! \details Bernstein and ECRYPT's ChaCha is _slightly_ different from the TLS working group's implementation for -//! cipher suites TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, -//! TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, and TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256. -//! \sa ChaCha, a variant of Salsa20 (2008.01.28). -//! \since Crypto++ 5.6.4 +/// \class ChaCha12 +/// \brief ChaCha12 stream cipher +/// \details Bernstein and ECRYPT's ChaCha is _slightly_ different from the TLS working group's implementation for +/// cipher suites TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, +/// TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, and TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256. +/// \sa ChaCha, a variant of Salsa20 (2008.01.28). +/// \since Crypto++ 5.6.4 struct ChaCha12 : public ChaCha_Info<12>, public SymmetricCipherDocumentation { typedef SymmetricCipherFinal, AdditiveCipherTemplate<> >, ChaCha_Info<12> > Encryption; typedef Encryption Decryption; }; -//! \class ChaCha20 -//! \brief ChaCha20 stream cipher -//! \sa ChaCha, a variant of Salsa20 (2008.01.28). -//! \details Bernstein and ECRYPT's ChaCha is _slightly_ different from the TLS working group's implementation for -//! cipher suites TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, -//! TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, and TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256. -//! \since Crypto++ 5.6.4 +/// \class ChaCha20 +/// \brief ChaCha20 stream cipher +/// \sa ChaCha, a variant of Salsa20 (2008.01.28). +/// \details Bernstein and ECRYPT's ChaCha is _slightly_ different from the TLS working group's implementation for +/// cipher suites TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, +/// TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, and TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256. +/// \since Crypto++ 5.6.4 struct ChaCha20 : public ChaCha_Info<20>, public SymmetricCipherDocumentation { typedef SymmetricCipherFinal, AdditiveCipherTemplate<> >, ChaCha_Info<20> > Encryption; diff --git a/channels.h b/channels.h index 9af4b461..7da9a813 100644 --- a/channels.h +++ b/channels.h @@ -1,8 +1,8 @@ // channels.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile channels.h -//! \brief Classes for multiple named channels +/// \file +/// \headerfile channels.h +/// \brief Classes for multiple named channels #ifndef CRYPTOPP_CHANNELS_H #define CRYPTOPP_CHANNELS_H @@ -20,7 +20,7 @@ NAMESPACE_BEGIN(CryptoPP) #if 0 -//! Route input on default channel to different and/or multiple channels based on message sequence number +/// Route input on default channel to different and/or multiple channels based on message sequence number class MessageSwitch : public Sink { public: @@ -93,7 +93,7 @@ protected: ChannelRouteIterator(); }; -//! Route input to different and/or multiple channels based on channel ID +/// Route input to different and/or multiple channels based on channel ID class CRYPTOPP_DLL ChannelSwitch : public Multichannel, public ChannelSwitchTypedefs { public: diff --git a/cmac.h b/cmac.h index 60482277..29dfb097 100644 --- a/cmac.h +++ b/cmac.h @@ -1,8 +1,8 @@ // cmac.h - originally written and placed in the public domain by Wei Dai -//! \file cmac.h -//! \brief Classes for CMAC message authentication code -//! \since Crypto++ 5.6.0 +/// \file cmac.h +/// \brief Classes for CMAC message authentication code +/// \since Crypto++ 5.6.0 #ifndef CRYPTOPP_CMAC_H #define CRYPTOPP_CMAC_H @@ -12,9 +12,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class CMAC_Base -//! \brief CMAC base implementation -//! \since Crypto++ 5.6.0 +/// \class CMAC_Base +/// \brief CMAC base implementation +/// \since Crypto++ 5.6.0 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CMAC_Base : public MessageAuthenticationCode { public: @@ -38,20 +38,20 @@ protected: unsigned int m_counter; }; -//! \brief CMAC message authentication code -//! \tparam T block cipher -//! \details Template parameter T should be a class derived from BlockCipherDocumentation, for example AES, with a block size of 8, 16, or 32. -//! \sa CMAC -//! \since Crypto++ 5.6.0 +/// \brief CMAC message authentication code +/// \tparam T block cipher +/// \details Template parameter T should be a class derived from BlockCipherDocumentation, for example AES, with a block size of 8, 16, or 32. +/// \sa CMAC +/// \since Crypto++ 5.6.0 template class CMAC : public MessageAuthenticationCodeImpl >, public SameKeyLengthAs { public: - //! \brief Construct a CMAC + /// \brief Construct a CMAC CMAC() {} - //! \brief Construct a CMAC - //! \param key the MAC key - //! \param length the key size, in bytes + /// \brief Construct a CMAC + /// \param key the MAC key + /// \param length the key size, in bytes CMAC(const byte *key, size_t length=SameKeyLengthAs::DEFAULT_KEYLENGTH) {this->SetKey(key, length);} diff --git a/config.h b/config.h index 01e60467..8038e9e4 100644 --- a/config.h +++ b/config.h @@ -1,7 +1,7 @@ // config.h - originally written and placed in the public domain by Wei Dai -//! \file config.h -//! \brief Library configuration file +/// \file config.h +/// \brief Library configuration file #ifndef CRYPTOPP_CONFIG_H #define CRYPTOPP_CONFIG_H @@ -163,15 +163,15 @@ #ifdef CRYPTOPP_DOXYGEN_PROCESSING // Document the namespce exists. Put it here before CryptoPP is undefined below. -//! \namespace CryptoPP -//! \brief Crypto++ library namespace -//! \details Nearly all classes are located in the CryptoPP namespace. Within -//! the namespace, there are two additional namespaces. -//!
    -//!
  • Name - namespace for names used with \p NameValuePairs and documented in argnames.h -//!
  • Test - namespace for testing and benchmarks classes -//!
  • Weak - namespace for weak and wounded algorithms, like ARC4, MD5 and Pananma -//!
+/// \namespace CryptoPP +/// \brief Crypto++ library namespace +/// \details Nearly all classes are located in the CryptoPP namespace. Within +/// the namespace, there are two additional namespaces. +///
    +///
  • Name - namespace for names used with \p NameValuePairs and documented in argnames.h +///
  • Test - namespace for testing and benchmarks classes +///
  • Weak - namespace for weak and wounded algorithms, like ARC4, MD5 and Pananma +///
namespace CryptoPP { } // Bring in the symbols fund in the weak namespace; and fold Weak1 into Weak # define CRYPTOPP_ENABLE_NAMESPACE_WEAK 1 diff --git a/cpu.h b/cpu.h index 481d578d..fa0158be 100644 --- a/cpu.h +++ b/cpu.h @@ -2,30 +2,30 @@ // updated for ARM and PowerPC by Jeffrey Walton. // updated to split CPU_Query() and CPU_Probe() by Jeffrey Walton. -//! \file cpu.h -//! \brief Functions for CPU features and intrinsics -//! \details The CPU functions are used in IA-32, ARM and PowerPC code paths. The -//! functions provide cpu specific feature testing on IA-32, ARM and PowerPC machines. -//! \details Feature detection uses CPUID on IA-32, like Intel and AMD. On other platforms -//! a two-part strategy is used. First, the library attempts to *Query* the OS for a feature, -//! like using Linux getauxval() or android_getCpuFeatures(). If that fails, then *Probe* -//! the cpu executing an instruction and an observe a SIGILL if unsupported. The general -//! pattern used by the library is: -//! 
-//!     g_hasCRC32 = CPU_QueryCRC32() || CPU_ProbeCRC32();
-//!     g_hasPMULL = CPU_QueryPMULL() || CPU_ProbePMULL();
-//!     g_hasAES  = CPU_QueryAES() || CPU_ProbeAES();
-//!
-//! \details Generally speaking, CPU_Query() is in the source file cpu.cpp because it -//! does not require special architectural flags. CPU_Probe() is in a source file that recieves -//! architectural flags, like sse-simd.cpp, neon-simd.cpp and -//! ppc-simd.cpp. For example, compiling neon-simd.cpp on an ARM64 machine will -//! have -march=armv8-a applied during a compile to make the instruction set architecture -//! (ISA) available. -//! \details The cpu probes are expensive when compared to a standard OS feature query. The library -//! also avoids probes on Apple platforms because Apple's signal handling for SIGILLs appears to -//! corrupt memory. CPU_Probe() will unconditionally return false for Apple platforms. OpenSSL -//! experienced the same problem and moved away from SIGILL probes on Apple. +/// \file cpu.h +/// \brief Functions for CPU features and intrinsics +/// \details The CPU functions are used in IA-32, ARM and PowerPC code paths. The +/// functions provide cpu specific feature testing on IA-32, ARM and PowerPC machines. +/// \details Feature detection uses CPUID on IA-32, like Intel and AMD. On other platforms +/// a two-part strategy is used. First, the library attempts to *Query* the OS for a feature, +/// like using Linux getauxval() or android_getCpuFeatures(). If that fails, then *Probe* +/// the cpu executing an instruction and an observe a SIGILL if unsupported. The general +/// pattern used by the library is: +/// 
+///     g_hasCRC32 = CPU_QueryCRC32() || CPU_ProbeCRC32();
+///     g_hasPMULL = CPU_QueryPMULL() || CPU_ProbePMULL();
+///     g_hasAES  = CPU_QueryAES() || CPU_ProbeAES();
+///
+/// \details Generally speaking, CPU_Query() is in the source file cpu.cpp because it +/// does not require special architectural flags. CPU_Probe() is in a source file that recieves +/// architectural flags, like sse-simd.cpp, neon-simd.cpp and +/// ppc-simd.cpp. For example, compiling neon-simd.cpp on an ARM64 machine will +/// have -march=armv8-a applied during a compile to make the instruction set architecture +/// (ISA) available. +/// \details The cpu probes are expensive when compared to a standard OS feature query. The library +/// also avoids probes on Apple platforms because Apple's signal handling for SIGILLs appears to +/// corrupt memory. CPU_Probe() will unconditionally return false for Apple platforms. OpenSSL +/// experienced the same problem and moved away from SIGILL probes on Apple. #ifndef CRYPTOPP_CPU_H #define CRYPTOPP_CPU_H @@ -103,14 +103,14 @@ CRYPTOPP_DLL void CRYPTOPP_API DetectX86Features(); CRYPTOPP_DLL bool CRYPTOPP_API CpuId(word32 func, word32 subfunc, word32 output[4]); #endif // CRYPTOPP_DOXYGEN_PROCESSING -//! \name IA-32 CPU FEATURES +/// \name IA-32 CPU FEATURES //@{ -//! \brief Determines SSE2 availability -//! \returns true if SSE2 is determined to be available, false otherwise -//! \details MMX, SSE and SSE2 are core processor features for x86_64, and -//! the function always returns true for the platform. -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines SSE2 availability +/// \returns true if SSE2 is determined to be available, false otherwise +/// \details MMX, SSE and SSE2 are core processor features for x86_64, and +/// the function always returns true for the platform. +/// \note This function is only available on Intel IA-32 platforms inline bool HasSSE2() { #if CRYPTOPP_BOOL_X64 @@ -122,10 +122,10 @@ inline bool HasSSE2() #endif } -//! \brief Determines SSSE3 availability -//! \returns true if SSSE3 is determined to be available, false otherwise -//! \details HasSSSE3() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines SSSE3 availability +/// \returns true if SSSE3 is determined to be available, false otherwise +/// \details HasSSSE3() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasSSSE3() { if (!g_x86DetectionDone) @@ -133,10 +133,10 @@ inline bool HasSSSE3() return g_hasSSSE3; } -//! \brief Determines SSE4.1 availability -//! \returns true if SSE4.1 is determined to be available, false otherwise -//! \details HasSSE41() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines SSE4.1 availability +/// \returns true if SSE4.1 is determined to be available, false otherwise +/// \details HasSSE41() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasSSE41() { if (!g_x86DetectionDone) @@ -144,10 +144,10 @@ inline bool HasSSE41() return g_hasSSE41; } -//! \brief Determines SSE4.2 availability -//! \returns true if SSE4.2 is determined to be available, false otherwise -//! \details HasSSE42() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines SSE4.2 availability +/// \returns true if SSE4.2 is determined to be available, false otherwise +/// \details HasSSE42() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasSSE42() { if (!g_x86DetectionDone) @@ -155,10 +155,10 @@ inline bool HasSSE42() return g_hasSSE42; } -//! \brief Determines AES-NI availability -//! \returns true if AES-NI is determined to be available, false otherwise -//! \details HasAESNI() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines AES-NI availability +/// \returns true if AES-NI is determined to be available, false otherwise +/// \details HasAESNI() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasAESNI() { if (!g_x86DetectionDone) @@ -166,10 +166,10 @@ inline bool HasAESNI() return g_hasAESNI; } -//! \brief Determines Carryless Multiply availability -//! \returns true if pclmulqdq is determined to be available, false otherwise -//! \details HasCLMUL() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines Carryless Multiply availability +/// \returns true if pclmulqdq is determined to be available, false otherwise +/// \details HasCLMUL() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasCLMUL() { if (!g_x86DetectionDone) @@ -177,10 +177,10 @@ inline bool HasCLMUL() return g_hasCLMUL; } -//! \brief Determines SHA availability -//! \returns true if SHA is determined to be available, false otherwise -//! \details HasSHA() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines SHA availability +/// \returns true if SHA is determined to be available, false otherwise +/// \details HasSHA() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasSHA() { if (!g_x86DetectionDone) @@ -188,10 +188,10 @@ inline bool HasSHA() return g_hasSHA; } -//! \brief Determines ADX availability -//! \returns true if ADX is determined to be available, false otherwise -//! \details HasADX() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines ADX availability +/// \returns true if ADX is determined to be available, false otherwise +/// \details HasADX() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasADX() { if (!g_x86DetectionDone) @@ -199,10 +199,10 @@ inline bool HasADX() return g_hasADX; } -//! \brief Determines if the CPU is an Intel P4 -//! \returns true if the CPU is a P4, false otherwise -//! \details IsP4() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines if the CPU is an Intel P4 +/// \returns true if the CPU is a P4, false otherwise +/// \details IsP4() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool IsP4() { if (!g_x86DetectionDone) @@ -210,10 +210,10 @@ inline bool IsP4() return g_isP4; } -//! \brief Determines RDRAND availability -//! \returns true if RDRAND is determined to be available, false otherwise -//! \details HasRDRAND() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines RDRAND availability +/// \returns true if RDRAND is determined to be available, false otherwise +/// \details HasRDRAND() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasRDRAND() { if (!g_x86DetectionDone) @@ -221,10 +221,10 @@ inline bool HasRDRAND() return g_hasRDRAND; } -//! \brief Determines RDSEED availability -//! \returns true if RDSEED is determined to be available, false otherwise -//! \details HasRDSEED() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines RDSEED availability +/// \returns true if RDSEED is determined to be available, false otherwise +/// \details HasRDSEED() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasRDSEED() { if (!g_x86DetectionDone) @@ -232,10 +232,10 @@ inline bool HasRDSEED() return g_hasRDSEED; } -//! \brief Determines Padlock RNG availability -//! \returns true if VIA Padlock RNG is determined to be available, false otherwise -//! \details HasPadlockRNG() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines Padlock RNG availability +/// \returns true if VIA Padlock RNG is determined to be available, false otherwise +/// \details HasPadlockRNG() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasPadlockRNG() { if (!g_x86DetectionDone) @@ -243,10 +243,10 @@ inline bool HasPadlockRNG() return g_hasPadlockRNG; } -//! \brief Determines Padlock ACE availability -//! \returns true if VIA Padlock ACE is determined to be available, false otherwise -//! \details HasPadlockACE() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines Padlock ACE availability +/// \returns true if VIA Padlock ACE is determined to be available, false otherwise +/// \details HasPadlockACE() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasPadlockACE() { if (!g_x86DetectionDone) @@ -254,10 +254,10 @@ inline bool HasPadlockACE() return g_hasPadlockACE; } -//! \brief Determines Padlock ACE2 availability -//! \returns true if VIA Padlock ACE2 is determined to be available, false otherwise -//! \details HasPadlockACE2() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines Padlock ACE2 availability +/// \returns true if VIA Padlock ACE2 is determined to be available, false otherwise +/// \details HasPadlockACE2() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasPadlockACE2() { if (!g_x86DetectionDone) @@ -265,10 +265,10 @@ inline bool HasPadlockACE2() return g_hasPadlockACE2; } -//! \brief Determines Padlock PHE availability -//! \returns true if VIA Padlock PHE is determined to be available, false otherwise -//! \details HasPadlockPHE() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines Padlock PHE availability +/// \returns true if VIA Padlock PHE is determined to be available, false otherwise +/// \details HasPadlockPHE() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasPadlockPHE() { if (!g_x86DetectionDone) @@ -276,10 +276,10 @@ inline bool HasPadlockPHE() return g_hasPadlockPHE; } -//! \brief Determines Padlock PMM availability -//! \returns true if VIA Padlock PMM is determined to be available, false otherwise -//! \details HasPadlockPMM() is a runtime check performed using CPUID -//! \note This function is only available on Intel IA-32 platforms +/// \brief Determines Padlock PMM availability +/// \returns true if VIA Padlock PMM is determined to be available, false otherwise +/// \details HasPadlockPMM() is a runtime check performed using CPUID +/// \note This function is only available on Intel IA-32 platforms inline bool HasPadlockPMM() { if (!g_x86DetectionDone) @@ -287,14 +287,14 @@ inline bool HasPadlockPMM() return g_hasPadlockPMM; } -//! \brief Provides the cache line size -//! \returns lower bound on the size of a cache line in bytes, if available -//! \details GetCacheLineSize() returns the lower bound on the size of a cache line, if it -//! is available. If the value is not available at runtime, then 32 is returned for a 32-bit -//! processor and 64 is returned for a 64-bit processor. -//! \details x86/x32/x64 uses CPUID to determine the value and it is usually accurate. PowerPC -//! and AIX also makes the value available to user space and it is also usually accurate. The -//! ARM processor equivalent is a privileged instruction, so a compile time value is returned. +/// \brief Provides the cache line size +/// \returns lower bound on the size of a cache line in bytes, if available +/// \details GetCacheLineSize() returns the lower bound on the size of a cache line, if it +/// is available. If the value is not available at runtime, then 32 is returned for a 32-bit +/// processor and 64 is returned for a 64-bit processor. +/// \details x86/x32/x64 uses CPUID to determine the value and it is usually accurate. PowerPC +/// and AIX also makes the value available to user space and it is also usually accurate. The +/// ARM processor equivalent is a privileged instruction, so a compile time value is returned. inline int GetCacheLineSize() { if (!g_x86DetectionDone) @@ -316,16 +316,16 @@ extern bool g_hasNEON, g_hasPMULL, g_hasCRC32, g_hasAES, g_hasSHA1, g_hasSHA2; void CRYPTOPP_API DetectArmFeatures(); #endif // CRYPTOPP_DOXYGEN_PROCESSING -//! \name ARM A-32, Aarch32 and AArch64 CPU FEATURES +/// \name ARM A-32, Aarch32 and AArch64 CPU FEATURES //@{ -//! \brief Determine if an ARM processor has Advanced SIMD available -//! \returns true if the hardware is capable of Advanced SIMD at runtime, false otherwise. -//! \details Advanced SIMD instructions are available under most ARMv7, Aarch32 and Aarch64. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -mfpu=neon (32-bit) or -march=armv8-a -//! (64-bit). Also see ARM's __ARM_NEON preprocessor macro. -//! \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms +/// \brief Determine if an ARM processor has Advanced SIMD available +/// \returns true if the hardware is capable of Advanced SIMD at runtime, false otherwise. +/// \details Advanced SIMD instructions are available under most ARMv7, Aarch32 and Aarch64. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -mfpu=neon (32-bit) or -march=armv8-a +/// (64-bit). Also see ARM's __ARM_NEON preprocessor macro. +/// \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms inline bool HasNEON() { // ASIMD is a core feature on Aarch32 and Aarch64 like SSE2 is a core feature on x86_64 @@ -338,13 +338,13 @@ inline bool HasNEON() #endif } -//! \brief Determine if an ARM processor provides Polynomial Multiplication -//! \returns true if the hardware is capable of polynomial multiplications at runtime, false otherwise. -//! \details The multiplication instructions are available under Aarch32 and Aarch64. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -march=armv8-a+crypto; while Apple requires -//! -arch arm64. Also see ARM's __ARM_FEATURE_CRYPTO preprocessor macro. -//! \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms +/// \brief Determine if an ARM processor provides Polynomial Multiplication +/// \returns true if the hardware is capable of polynomial multiplications at runtime, false otherwise. +/// \details The multiplication instructions are available under Aarch32 and Aarch64. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -march=armv8-a+crypto; while Apple requires +/// -arch arm64. Also see ARM's __ARM_FEATURE_CRYPTO preprocessor macro. +/// \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms inline bool HasPMULL() { #if defined(__aarch32__) || defined(__aarch64__) @@ -356,14 +356,14 @@ inline bool HasPMULL() #endif } -//! \brief Determine if an ARM processor has CRC32 available -//! \returns true if the hardware is capable of CRC32 at runtime, false otherwise. -//! \details CRC32 instructions provide access to the processor's CRC-32 and CRC-32C instructions. -//! They are provided by ARM C Language Extensions 2.0 (ACLE 2.0) and available under Aarch32 and Aarch64. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -march=armv8-a+crc; while Apple requires -//! -arch arm64. Also see ARM's __ARM_FEATURE_CRC32 preprocessor macro. -//! \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms +/// \brief Determine if an ARM processor has CRC32 available +/// \returns true if the hardware is capable of CRC32 at runtime, false otherwise. +/// \details CRC32 instructions provide access to the processor's CRC-32 and CRC-32C instructions. +/// They are provided by ARM C Language Extensions 2.0 (ACLE 2.0) and available under Aarch32 and Aarch64. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -march=armv8-a+crc; while Apple requires +/// -arch arm64. Also see ARM's __ARM_FEATURE_CRC32 preprocessor macro. +/// \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms inline bool HasCRC32() { #if defined(__aarch32__) || defined(__aarch64__) @@ -375,14 +375,14 @@ inline bool HasCRC32() #endif } -//! \brief Determine if an ARM processor has AES available -//! \returns true if the hardware is capable of AES at runtime, false otherwise. -//! \details AES is part of the optional Crypto extensions on Aarch32 and Aarch64. They are -//! accessed using ARM C Language Extensions 2.0 (ACLE 2.0). -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -march=armv8-a+crypto; while Apple requires -//! -arch arm64. Also see ARM's __ARM_FEATURE_CRYPTO preprocessor macro. -//! \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms +/// \brief Determine if an ARM processor has AES available +/// \returns true if the hardware is capable of AES at runtime, false otherwise. +/// \details AES is part of the optional Crypto extensions on Aarch32 and Aarch64. They are +/// accessed using ARM C Language Extensions 2.0 (ACLE 2.0). +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -march=armv8-a+crypto; while Apple requires +/// -arch arm64. Also see ARM's __ARM_FEATURE_CRYPTO preprocessor macro. +/// \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms inline bool HasAES() { #if defined(__aarch32__) || defined(__aarch64__) @@ -394,14 +394,14 @@ inline bool HasAES() #endif } -//! \brief Determine if an ARM processor has SHA1 available -//! \returns true if the hardware is capable of SHA1 at runtime, false otherwise. -//! \details SHA1 is part of the optional Crypto extensions on Aarch32 and Aarch64. They are -//! accessed using ARM C Language Extensions 2.0 (ACLE 2.0). -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -march=armv8-a+crypto; while Apple requires -//! -arch arm64. Also see ARM's __ARM_FEATURE_CRYPTO preprocessor macro. -//! \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms +/// \brief Determine if an ARM processor has SHA1 available +/// \returns true if the hardware is capable of SHA1 at runtime, false otherwise. +/// \details SHA1 is part of the optional Crypto extensions on Aarch32 and Aarch64. They are +/// accessed using ARM C Language Extensions 2.0 (ACLE 2.0). +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -march=armv8-a+crypto; while Apple requires +/// -arch arm64. Also see ARM's __ARM_FEATURE_CRYPTO preprocessor macro. +/// \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms inline bool HasSHA1() { #if defined(__aarch32__) || defined(__aarch64__) @@ -413,14 +413,14 @@ inline bool HasSHA1() #endif } -//! \brief Determine if an ARM processor has SHA2 available -//! \returns true if the hardware is capable of SHA2 at runtime, false otherwise. -//! \details SHA2 is part of the optional Crypto extensions on Aarch32 and Aarch64. They are -//! accessed using ARM C Language Extensions 2.0 (ACLE 2.0). -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -march=armv8-a+crypto; while Apple requires -//! -arch arm64. Also see ARM's __ARM_FEATURE_CRYPTO preprocessor macro. -//! \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms +/// \brief Determine if an ARM processor has SHA2 available +/// \returns true if the hardware is capable of SHA2 at runtime, false otherwise. +/// \details SHA2 is part of the optional Crypto extensions on Aarch32 and Aarch64. They are +/// accessed using ARM C Language Extensions 2.0 (ACLE 2.0). +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -march=armv8-a+crypto; while Apple requires +/// -arch arm64. Also see ARM's __ARM_FEATURE_CRYPTO preprocessor macro. +/// \note This function is only available on ARM-32, Aarch32 and Aarch64 platforms inline bool HasSHA2() { #if defined(__aarch32__) || defined(__aarch64__) @@ -448,19 +448,19 @@ extern word32 g_cacheLineSize; void CRYPTOPP_API DetectPowerpcFeatures(); #endif // CRYPTOPP_DOXYGEN_PROCESSING -//! \name POWERPC CPU FEATURES +/// \name POWERPC CPU FEATURES //@{ -//! \brief Determine if a PowerPC processor has Altivec available -//! \returns true if the hardware is capable of Altivec at runtime, false otherwise. -//! \details Altivec instructions are available under most modern PowerPCs. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -mcpu=power7; while IBM XL C/C++ compilers require -//! -qarch=pwr7 -qaltivec. Also see PowerPC's _ALTIVEC_ preprocessor macro. -//! \details Atilvec was first available on Power4 platforms. However Crypto++ releies on unaligned -//! loads and stores which is a Power7 feature. If the platform lacks Power7 extensions, then the -//! GNUmakefile sets -DCRYPTOPP_DISABLE_ALTIVEC. -//! \note This function is only available on PowerPC and PowerPC-64 platforms +/// \brief Determine if a PowerPC processor has Altivec available +/// \returns true if the hardware is capable of Altivec at runtime, false otherwise. +/// \details Altivec instructions are available under most modern PowerPCs. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -mcpu=power7; while IBM XL C/C++ compilers require +/// -qarch=pwr7 -qaltivec. Also see PowerPC's _ALTIVEC_ preprocessor macro. +/// \details Atilvec was first available on Power4 platforms. However Crypto++ releies on unaligned +/// loads and stores which is a Power7 feature. If the platform lacks Power7 extensions, then the +/// GNUmakefile sets -DCRYPTOPP_DISABLE_ALTIVEC. +/// \note This function is only available on PowerPC and PowerPC-64 platforms inline bool HasAltivec() { if (!g_PowerpcDetectionDone) @@ -468,16 +468,16 @@ inline bool HasAltivec() return g_hasAltivec; } -//! \brief Determine if a PowerPC processor has Power8 available -//! \returns true if the hardware is capable of Power8 at runtime, false otherwise. -//! \details Altivec instructions are available under most modern PowerPCs. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -mcpu=power8; while IBM XL C/C++ compilers require -//! -qarch=pwr8 -qaltivec. Also see PowerPC's _ALTIVEC_ preprocessor macro. -//! \details Atilvec was first available on Power4 platforms. However Crypto++ releies on unaligned -//! loads and stores which is a Power7 feature. If the platform lacks Power7 extensions, then the -//! GNUmakefile sets -DCRYPTOPP_DISABLE_ALTIVEC. -//! \note This function is only available on PowerPC and PowerPC-64 platforms +/// \brief Determine if a PowerPC processor has Power8 available +/// \returns true if the hardware is capable of Power8 at runtime, false otherwise. +/// \details Altivec instructions are available under most modern PowerPCs. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -mcpu=power8; while IBM XL C/C++ compilers require +/// -qarch=pwr8 -qaltivec. Also see PowerPC's _ALTIVEC_ preprocessor macro. +/// \details Atilvec was first available on Power4 platforms. However Crypto++ releies on unaligned +/// loads and stores which is a Power7 feature. If the platform lacks Power7 extensions, then the +/// GNUmakefile sets -DCRYPTOPP_DISABLE_ALTIVEC. +/// \note This function is only available on PowerPC and PowerPC-64 platforms inline bool HasPower7() { if (!g_PowerpcDetectionDone) @@ -485,16 +485,16 @@ inline bool HasPower7() return g_hasPower7; } -//! \brief Determine if a PowerPC processor has Power8 available -//! \returns true if the hardware is capable of Power8 at runtime, false otherwise. -//! \details Altivec instructions are available under most modern PowerPCs. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -mcpu=power8; while IBM XL C/C++ compilers require -//! -qarch=pwr8 -qaltivec. Also see PowerPC's _ALTIVEC_ preprocessor macro. -//! \details Atilvec was first available on Power4 platforms. However Crypto++ releies on unaligned -//! loads and stores which is a Power7 feature. If the platform lacks Power7 extensions, then the -//! GNUmakefile sets -DCRYPTOPP_DISABLE_ALTIVEC. -//! \note This function is only available on PowerPC and PowerPC-64 platforms +/// \brief Determine if a PowerPC processor has Power8 available +/// \returns true if the hardware is capable of Power8 at runtime, false otherwise. +/// \details Altivec instructions are available under most modern PowerPCs. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -mcpu=power8; while IBM XL C/C++ compilers require +/// -qarch=pwr8 -qaltivec. Also see PowerPC's _ALTIVEC_ preprocessor macro. +/// \details Atilvec was first available on Power4 platforms. However Crypto++ releies on unaligned +/// loads and stores which is a Power7 feature. If the platform lacks Power7 extensions, then the +/// GNUmakefile sets -DCRYPTOPP_DISABLE_ALTIVEC. +/// \note This function is only available on PowerPC and PowerPC-64 platforms inline bool HasPower8() { if (!g_PowerpcDetectionDone) @@ -502,13 +502,13 @@ inline bool HasPower8() return g_hasPower8; } -//! \brief Determine if a PowerPC processor has AES available -//! \returns true if the hardware is capable of AES at runtime, false otherwise. -//! \details AES is part of the in-crypto extensions on Power8 and Power9. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -mcpu=power8; while IBM XL C/C++ compilers require -//! -qarch=pwr8 -qaltivec. Also see PowerPC's __CRYPTO preprocessor macro. -//! \note This function is only available on PowerPC and PowerPC-64 platforms +/// \brief Determine if a PowerPC processor has AES available +/// \returns true if the hardware is capable of AES at runtime, false otherwise. +/// \details AES is part of the in-crypto extensions on Power8 and Power9. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -mcpu=power8; while IBM XL C/C++ compilers require +/// -qarch=pwr8 -qaltivec. Also see PowerPC's __CRYPTO preprocessor macro. +/// \note This function is only available on PowerPC and PowerPC-64 platforms inline bool HasAES() { if (!g_PowerpcDetectionDone) @@ -516,13 +516,13 @@ inline bool HasAES() return g_hasAES; } -//! \brief Determine if a PowerPC processor has SHA256 available -//! \returns true if the hardware is capable of SHA256 at runtime, false otherwise. -//! \details SHA is part of the in-crypto extensions on Power8 and Power9. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -mcpu=power8; while IBM XL C/C++ compilers require -//! -qarch=pwr8 -qaltivec. Also see PowerPC's __CRYPTO preprocessor macro. -//! \note This function is only available on PowerPC and PowerPC-64 platforms +/// \brief Determine if a PowerPC processor has SHA256 available +/// \returns true if the hardware is capable of SHA256 at runtime, false otherwise. +/// \details SHA is part of the in-crypto extensions on Power8 and Power9. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -mcpu=power8; while IBM XL C/C++ compilers require +/// -qarch=pwr8 -qaltivec. Also see PowerPC's __CRYPTO preprocessor macro. +/// \note This function is only available on PowerPC and PowerPC-64 platforms inline bool HasSHA256() { if (!g_PowerpcDetectionDone) @@ -530,13 +530,13 @@ inline bool HasSHA256() return g_hasSHA256; } -//! \brief Determine if a PowerPC processor has SHA512 available -//! \returns true if the hardware is capable of SHA512 at runtime, false otherwise. -//! \details SHA is part of the in-crypto extensions on Power8 and Power9. -//! \details Runtime support requires compile time support. When compiling with GCC, you may -//! need to compile with -mcpu=power8; while IBM XL C/C++ compilers require -//! -qarch=pwr8 -qaltivec. Also see PowerPC's __CRYPTO preprocessor macro. -//! \note This function is only available on PowerPC and PowerPC-64 platforms +/// \brief Determine if a PowerPC processor has SHA512 available +/// \returns true if the hardware is capable of SHA512 at runtime, false otherwise. +/// \details SHA is part of the in-crypto extensions on Power8 and Power9. +/// \details Runtime support requires compile time support. When compiling with GCC, you may +/// need to compile with -mcpu=power8; while IBM XL C/C++ compilers require +/// -qarch=pwr8 -qaltivec. Also see PowerPC's __CRYPTO preprocessor macro. +/// \note This function is only available on PowerPC and PowerPC-64 platforms inline bool HasSHA512() { if (!g_PowerpcDetectionDone) @@ -544,14 +544,14 @@ inline bool HasSHA512() return g_hasSHA512; } -//! \brief Provides the cache line size -//! \returns lower bound on the size of a cache line in bytes, if available -//! \details GetCacheLineSize() returns the lower bound on the size of a cache line, if it -//! is available. If the value is not available at runtime, then 32 is returned for a 32-bit -//! processor and 64 is returned for a 64-bit processor. -//! \details x86/x32/x64 uses CPUID to determine the value and it is usually accurate. PowerPC -//! and AIX also makes the value available to user space and it is also usually accurate. The -//! ARM processor equivalent is a privileged instruction, so a compile time value is returned. +/// \brief Provides the cache line size +/// \returns lower bound on the size of a cache line in bytes, if available +/// \details GetCacheLineSize() returns the lower bound on the size of a cache line, if it +/// is available. If the value is not available at runtime, then 32 is returned for a 32-bit +/// processor and 64 is returned for a 64-bit processor. +/// \details x86/x32/x64 uses CPUID to determine the value and it is usually accurate. PowerPC +/// and AIX also makes the value available to user space and it is also usually accurate. The +/// ARM processor equivalent is a privileged instruction, so a compile time value is returned. inline int GetCacheLineSize() { if (!g_PowerpcDetectionDone) @@ -567,14 +567,14 @@ inline int GetCacheLineSize() // Non-Intel systems #if !(CRYPTOPP_BOOL_X86 || CRYPTOPP_BOOL_X32 || CRYPTOPP_BOOL_X64 || CRYPTOPP_BOOL_PPC32 || CRYPTOPP_BOOL_PPC64) -//! \brief Provides the cache line size -//! \returns lower bound on the size of a cache line in bytes, if available -//! \details GetCacheLineSize() returns the lower bound on the size of a cache line, if it -//! is available. If the value is not available at runtime, then 32 is returned for a 32-bit -//! processor and 64 is returned for a 64-bit processor. -//! \details x86/x32/x64 uses CPUID to determine the value and it is usually accurate. PowerPC -//! and AIX also makes the value available to user space and it is also usually accurate. The -//! ARM processor equivalent is a privileged instruction, so a compile time value is returned. +/// \brief Provides the cache line size +/// \returns lower bound on the size of a cache line in bytes, if available +/// \details GetCacheLineSize() returns the lower bound on the size of a cache line, if it +/// is available. If the value is not available at runtime, then 32 is returned for a 32-bit +/// processor and 64 is returned for a 64-bit processor. +/// \details x86/x32/x64 uses CPUID to determine the value and it is usually accurate. PowerPC +/// and AIX also makes the value available to user space and it is also usually accurate. The +/// ARM processor equivalent is a privileged instruction, so a compile time value is returned. inline int GetCacheLineSize() { return CRYPTOPP_L1_CACHE_LINE_SIZE; diff --git a/crc.h b/crc.h index 0334f705..08a20a64 100644 --- a/crc.h +++ b/crc.h @@ -1,8 +1,8 @@ // crc.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile crc.h -//! \brief Classes for CRC-32 and CRC-32C checksum algorithm +/// \file +/// \headerfile crc.h +/// \brief Classes for CRC-32 and CRC-32C checksum algorithm #ifndef CRYPTOPP_CRC32_H #define CRYPTOPP_CRC32_H @@ -21,8 +21,8 @@ const word32 CRC32_NEGL = 0xffffffffL; #define CRC32_SHIFTED(c) (c << 8) #endif -//! \brief CRC-32 Checksum Calculation -//! \details Uses CRC polynomial 0xEDB88320 +/// \brief CRC-32 Checksum Calculation +/// \details Uses CRC polynomial 0xEDB88320 class CRC32 : public HashTransformation { public: @@ -45,9 +45,9 @@ private: word32 m_crc; }; -//! \brief CRC-32C Checksum Calculation -//! \details Uses CRC polynomial 0x82F63B78 -//! \since Crypto++ 5.6.4 +/// \brief CRC-32C Checksum Calculation +/// \details Uses CRC polynomial 0x82F63B78 +/// \since Crypto++ 5.6.4 class CRC32C : public HashTransformation { public: diff --git a/cryptlib.cpp b/cryptlib.cpp index a9722159..03f0f0ff 100644 --- a/cryptlib.cpp +++ b/cryptlib.cpp @@ -330,28 +330,28 @@ void RandomNumberGenerator::GenerateIntoBufferedTransformation(BufferedTransform } } -//! \class ClassNullRNG -//! \brief Random Number Generator that does not produce random numbers -//! \details ClassNullRNG can be used for functions that require a RandomNumberGenerator -//! but don't actually use it. The class throws NotImplemented when a generation function is called. -//! \sa NullRNG() +/// \class ClassNullRNG +/// \brief Random Number Generator that does not produce random numbers +/// \details ClassNullRNG can be used for functions that require a RandomNumberGenerator +/// but don't actually use it. The class throws NotImplemented when a generation function is called. +/// \sa NullRNG() class ClassNullRNG : public RandomNumberGenerator { public: - //! \brief The name of the generator - //! \returns the string \a NullRNGs + /// \brief The name of the generator + /// \returns the string \a NullRNGs std::string AlgorithmName() const {return "NullRNG";} #if defined(CRYPTOPP_DOXYGEN_PROCESSING) - //! \brief An implementation that throws NotImplemented + /// \brief An implementation that throws NotImplemented byte GenerateByte () {} - //! \brief An implementation that throws NotImplemented + /// \brief An implementation that throws NotImplemented unsigned int GenerateBit () {} - //! \brief An implementation that throws NotImplemented + /// \brief An implementation that throws NotImplemented word32 GenerateWord32 (word32 min, word32 max) {} #endif - //! \brief An implementation that throws NotImplemented + /// \brief An implementation that throws NotImplemented void GenerateBlock(byte *output, size_t size) { CRYPTOPP_UNUSED(output); CRYPTOPP_UNUSED(size); @@ -359,15 +359,15 @@ public: } #if defined(CRYPTOPP_DOXYGEN_PROCESSING) - //! \brief An implementation that throws NotImplemented + /// \brief An implementation that throws NotImplemented void GenerateIntoBufferedTransformation (BufferedTransformation &target, const std::string &channel, lword length) {} - //! \brief An implementation that throws NotImplemented + /// \brief An implementation that throws NotImplemented void IncorporateEntropy (const byte *input, size_t length) {} - //! \brief An implementation that returns \p false + /// \brief An implementation that returns \p false bool CanIncorporateEntropy () const {} - //! \brief An implementation that does nothing + /// \brief An implementation that does nothing void DiscardBytes (size_t n) {} - //! \brief An implementation that does nothing + /// \brief An implementation that does nothing void Shuffle (IT begin, IT end) {} private: diff --git a/cryptlib.h b/cryptlib.h index 644f4790..272659cc 100644 --- a/cryptlib.h +++ b/cryptlib.h @@ -1,7 +1,7 @@ // cryptlib.h - originally written and placed in the public domain by Wei Dai -//! \file cryptlib.h -//! \brief Abstract base classes that provide a uniform interface to this library. +/// \file cryptlib.h +/// \brief Abstract base classes that provide a uniform interface to this library. /*! \mainpage Crypto++ Library 6.0 API Reference
@@ -116,80 +116,80 @@ class Integer; class RandomNumberGenerator; class BufferedTransformation; -//! \brief Specifies a direction for a cipher to operate -//! \sa BlockTransformation::IsForwardTransformation(), BlockTransformation::IsPermutation(), BlockTransformation::GetCipherDirection() +/// \brief Specifies a direction for a cipher to operate +/// \sa BlockTransformation::IsForwardTransformation(), BlockTransformation::IsPermutation(), BlockTransformation::GetCipherDirection() enum CipherDir { - //! \brief the cipher is performing encryption + /// \brief the cipher is performing encryption ENCRYPTION, - //! \brief the cipher is performing decryption + /// \brief the cipher is performing decryption DECRYPTION}; -//! \brief Represents infinite time +/// \brief Represents infinite time const unsigned long INFINITE_TIME = ULONG_MAX; // VC60 workaround: using enums as template parameters causes problems -//! \brief Converts an enumeration to a type suitable for use as a template parameter +/// \brief Converts an enumeration to a type suitable for use as a template parameter template struct EnumToType { static ENUM_TYPE ToEnum() {return (ENUM_TYPE)VALUE;} }; -//! \brief Provides the byte ordering -//! \details Big-endian and little-endian modes are supported. Bi-endian and PDP-endian modes -//! are not supported. +/// \brief Provides the byte ordering +/// \details Big-endian and little-endian modes are supported. Bi-endian and PDP-endian modes +/// are not supported. enum ByteOrder { - //! \brief byte order is little-endian + /// \brief byte order is little-endian LITTLE_ENDIAN_ORDER = 0, - //! \brief byte order is big-endian + /// \brief byte order is big-endian BIG_ENDIAN_ORDER = 1}; -//! \brief Provides a constant for LittleEndian +/// \brief Provides a constant for LittleEndian typedef EnumToType LittleEndian; -//! \brief Provides a constant for BigEndian +/// \brief Provides a constant for BigEndian typedef EnumToType BigEndian; -//! \class Exception -//! \brief Base class for all exceptions thrown by the library -//! \details All library exceptions directly or indirectly inherit from the Exception class. -//! The Exception class itself inherits from std::exception. The library does not use -//! std::runtime_error derived classes. +/// \class Exception +/// \brief Base class for all exceptions thrown by the library +/// \details All library exceptions directly or indirectly inherit from the Exception class. +/// The Exception class itself inherits from std::exception. The library does not use +/// std::runtime_error derived classes. class CRYPTOPP_DLL Exception : public std::exception { public: - //! \enum ErrorType - //! \brief Error types or categories + /// \enum ErrorType + /// \brief Error types or categories enum ErrorType { - //! \brief A method was called which was not implemented + /// \brief A method was called which was not implemented NOT_IMPLEMENTED, - //! \brief An invalid argument was detected + /// \brief An invalid argument was detected INVALID_ARGUMENT, - //! \brief BufferedTransformation received a Flush(true) signal but can't flush buffers + /// \brief BufferedTransformation received a Flush(true) signal but can't flush buffers CANNOT_FLUSH, - //! \brief Data integerity check, such as CRC or MAC, failed + /// \brief Data integerity check, such as CRC or MAC, failed DATA_INTEGRITY_CHECK_FAILED, - //! \brief Input data was received that did not conform to expected format + /// \brief Input data was received that did not conform to expected format INVALID_DATA_FORMAT, - //! \brief Error reading from input device or writing to output device + /// \brief Error reading from input device or writing to output device IO_ERROR, - //! \brief Some other error occurred not belonging to other categories + /// \brief Some other error occurred not belonging to other categories OTHER_ERROR }; virtual ~Exception() throw() {} - //! \brief Construct a new Exception + /// \brief Construct a new Exception explicit Exception(ErrorType errorType, const std::string &s) : m_errorType(errorType), m_what(s) {} - //! \brief Retrieves a C-string describing the exception + /// \brief Retrieves a C-string describing the exception const char *what() const throw() {return (m_what.c_str());} - //! \brief Retrieves a string describing the exception + /// \brief Retrieves a string describing the exception const std::string &GetWhat() const {return m_what;} - //! \brief Sets the error string for the exception + /// \brief Sets the error string for the exception void SetWhat(const std::string &s) {m_what = s;} - //! \brief Retrieves the error type for the exception + /// \brief Retrieves the error type for the exception ErrorType GetErrorType() const {return m_errorType;} - //! \brief Sets the error type for the exceptions + /// \brief Sets the error type for the exceptions void SetErrorType(ErrorType errorType) {m_errorType = errorType;} private: @@ -197,42 +197,42 @@ private: std::string m_what; }; -//! \brief An invalid argument was detected +/// \brief An invalid argument was detected class CRYPTOPP_DLL InvalidArgument : public Exception { public: explicit InvalidArgument(const std::string &s) : Exception(INVALID_ARGUMENT, s) {} }; -//! \brief Input data was received that did not conform to expected format +/// \brief Input data was received that did not conform to expected format class CRYPTOPP_DLL InvalidDataFormat : public Exception { public: explicit InvalidDataFormat(const std::string &s) : Exception(INVALID_DATA_FORMAT, s) {} }; -//! \brief A decryption filter encountered invalid ciphertext +/// \brief A decryption filter encountered invalid ciphertext class CRYPTOPP_DLL InvalidCiphertext : public InvalidDataFormat { public: explicit InvalidCiphertext(const std::string &s) : InvalidDataFormat(s) {} }; -//! \brief A method was called which was not implemented +/// \brief A method was called which was not implemented class CRYPTOPP_DLL NotImplemented : public Exception { public: explicit NotImplemented(const std::string &s) : Exception(NOT_IMPLEMENTED, s) {} }; -//! \brief Flush(true) was called but it can't completely flush its buffers +/// \brief Flush(true) was called but it can't completely flush its buffers class CRYPTOPP_DLL CannotFlush : public Exception { public: explicit CannotFlush(const std::string &s) : Exception(CANNOT_FLUSH, s) {} }; -//! \brief The operating system reported an error +/// \brief The operating system reported an error class CRYPTOPP_DLL OS_Error : public Exception { public: @@ -240,9 +240,9 @@ public: OS_Error(ErrorType errorType, const std::string &s, const std::string& operation, int errorCode) : Exception(errorType, s), m_operation(operation), m_errorCode(errorCode) {} - //! \brief Retrieve the operating system API that reported the error + /// \brief Retrieve the operating system API that reported the error const std::string & GetOperation() const {return m_operation;} - //! \brief Retrieve the error code returned by the operating system + /// \brief Retrieve the error code returned by the operating system int GetErrorCode() const {return m_errorCode;} protected: @@ -250,72 +250,72 @@ protected: int m_errorCode; }; -//! \class DecodingResult -//! \brief Returns a decoding results +/// \class DecodingResult +/// \brief Returns a decoding results struct CRYPTOPP_DLL DecodingResult { - //! \brief Constructs a DecodingResult - //! \details isValidCoding is initialized to false and messageLength is initialized to 0. + /// \brief Constructs a DecodingResult + /// \details isValidCoding is initialized to false and messageLength is initialized to 0. explicit DecodingResult() : isValidCoding(false), messageLength(0) {} - //! \brief Constructs a DecodingResult - //! \param len the message length - //! \details isValidCoding is initialized to true. + /// \brief Constructs a DecodingResult + /// \param len the message length + /// \details isValidCoding is initialized to true. explicit DecodingResult(size_t len) : isValidCoding(true), messageLength(len) {} - //! \brief Compare two DecodingResult - //! \param rhs the other DecodingResult - //! \return true if both isValidCoding and messageLength are equal, false otherwise + /// \brief Compare two DecodingResult + /// \param rhs the other DecodingResult + /// \return true if both isValidCoding and messageLength are equal, false otherwise bool operator==(const DecodingResult &rhs) const {return isValidCoding == rhs.isValidCoding && messageLength == rhs.messageLength;} - //! \brief Compare two DecodingResult - //! \param rhs the other DecodingResult - //! \return true if either isValidCoding or messageLength is \a not equal, false otherwise - //! \details Returns !operator==(rhs). + /// \brief Compare two DecodingResult + /// \param rhs the other DecodingResult + /// \return true if either isValidCoding or messageLength is \a not equal, false otherwise + /// \details Returns !operator==(rhs). bool operator!=(const DecodingResult &rhs) const {return !operator==(rhs);} - //! \brief Flag to indicate the decoding is valid + /// \brief Flag to indicate the decoding is valid bool isValidCoding; - //! \brief Recovered message length if isValidCoding is true, undefined otherwise + /// \brief Recovered message length if isValidCoding is true, undefined otherwise size_t messageLength; }; -//! \class NameValuePairs -//! \brief Interface for retrieving values given their names -//! \details This class is used to safely pass a variable number of arbitrarily typed arguments to functions -//! and to read values from keys and crypto parameters. -//! \details To obtain an object that implements NameValuePairs for the purpose of parameter -//! passing, use the MakeParameters() function. -//! \details To get a value from NameValuePairs, you need to know the name and the type of the value. -//! Call GetValueNames() on a NameValuePairs object to obtain a list of value names that it supports. -//! then look at the Name namespace documentation to see what the type of each value is, or -//! alternatively, call GetIntValue() with the value name, and if the type is not int, a -//! ValueTypeMismatch exception will be thrown and you can get the actual type from the exception object. -//! \sa NullNameValuePairs, g_nullNameValuePairs, -//! NameValuePairs on the Crypto++ wiki +/// \class NameValuePairs +/// \brief Interface for retrieving values given their names +/// \details This class is used to safely pass a variable number of arbitrarily typed arguments to functions +/// and to read values from keys and crypto parameters. +/// \details To obtain an object that implements NameValuePairs for the purpose of parameter +/// passing, use the MakeParameters() function. +/// \details To get a value from NameValuePairs, you need to know the name and the type of the value. +/// Call GetValueNames() on a NameValuePairs object to obtain a list of value names that it supports. +/// then look at the Name namespace documentation to see what the type of each value is, or +/// alternatively, call GetIntValue() with the value name, and if the type is not int, a +/// ValueTypeMismatch exception will be thrown and you can get the actual type from the exception object. +/// \sa NullNameValuePairs, g_nullNameValuePairs, +/// NameValuePairs on the Crypto++ wiki class NameValuePairs { public: virtual ~NameValuePairs() {} - //! \class ValueTypeMismatch - //! \brief Thrown when an unexpected type is encountered - //! \details Exception thrown when trying to retrieve a value using a different type than expected + /// \class ValueTypeMismatch + /// \brief Thrown when an unexpected type is encountered + /// \details Exception thrown when trying to retrieve a value using a different type than expected class CRYPTOPP_DLL ValueTypeMismatch : public InvalidArgument { public: - //! \brief Construct a ValueTypeMismatch - //! \param name the name of the value - //! \param stored the \a actual type of the value stored - //! \param retrieving the \a presumed type of the value retrieved + /// \brief Construct a ValueTypeMismatch + /// \param name the name of the value + /// \param stored the \a actual type of the value stored + /// \param retrieving the \a presumed type of the value retrieved ValueTypeMismatch(const std::string &name, const std::type_info &stored, const std::type_info &retrieving) : InvalidArgument("NameValuePairs: type mismatch for '" + name + "', stored '" + stored.name() + "', trying to retrieve '" + retrieving.name() + "'") , m_stored(stored), m_retrieving(retrieving) {} - //! \brief Provides the stored type - //! \return the C++ mangled name of the type + /// \brief Provides the stored type + /// \return the C++ mangled name of the type const std::type_info & GetStoredTypeInfo() const {return m_stored;} - //! \brief Provides the retrieveing type - //! \return the C++ mangled name of the type + /// \brief Provides the retrieveing type + /// \return the C++ mangled name of the type const std::type_info & GetRetrievingTypeInfo() const {return m_retrieving;} private: @@ -323,44 +323,44 @@ public: const std::type_info &m_retrieving; }; - //! \brief Get a copy of this object or subobject - //! \tparam T class or type - //! \param object reference to a variable that receives the value + /// \brief Get a copy of this object or subobject + /// \tparam T class or type + /// \param object reference to a variable that receives the value template bool GetThisObject(T &object) const { return GetValue((std::string("ThisObject:")+typeid(T).name()).c_str(), object); } - //! \brief Get a pointer to this object - //! \tparam T class or type - //! \param ptr reference to a pointer to a variable that receives the value + /// \brief Get a pointer to this object + /// \tparam T class or type + /// \param ptr reference to a pointer to a variable that receives the value template bool GetThisPointer(T *&ptr) const { return GetValue((std::string("ThisPointer:")+typeid(T).name()).c_str(), ptr); } - //! \brief Get a named value - //! \tparam T class or type - //! \param name the name of the object or value to retrieve - //! \param value reference to a variable that receives the value - //! \returns true if the value was retrieved, false otherwise - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Get a named value + /// \tparam T class or type + /// \param name the name of the object or value to retrieve + /// \param value reference to a variable that receives the value + /// \returns true if the value was retrieved, false otherwise + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() template bool GetValue(const char *name, T &value) const { return GetVoidValue(name, typeid(T), &value); } - //! \brief Get a named value - //! \tparam T class or type - //! \param name the name of the object or value to retrieve - //! \param defaultValue the default value of the class or type if it does not exist - //! \return the object or value - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Get a named value + /// \tparam T class or type + /// \param name the name of the object or value to retrieve + /// \param defaultValue the default value of the class or type if it does not exist + /// \return the object or value + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() template T GetValueWithDefault(const char *name, T defaultValue) const { @@ -371,54 +371,54 @@ public: return defaultValue; } - //! \brief Get a list of value names that can be retrieved - //! \return a list of names available to retrieve - //! \details the items in the list are delimited with a colon. + /// \brief Get a list of value names that can be retrieved + /// \return a list of names available to retrieve + /// \details the items in the list are delimited with a colon. CRYPTOPP_DLL std::string GetValueNames() const {std::string result; GetValue("ValueNames", result); return result;} - //! \brief Get a named value with type int - //! \param name the name of the value to retrieve - //! \param value the value retrieved upon success - //! \return true if an int value was retrieved, false otherwise - //! \details GetIntValue() is used to ensure we don't accidentally try to get an - //! unsigned int or some other type when we mean int (which is the most common case) - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Get a named value with type int + /// \param name the name of the value to retrieve + /// \param value the value retrieved upon success + /// \return true if an int value was retrieved, false otherwise + /// \details GetIntValue() is used to ensure we don't accidentally try to get an + /// unsigned int or some other type when we mean int (which is the most common case) + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() CRYPTOPP_DLL bool GetIntValue(const char *name, int &value) const {return GetValue(name, value);} - //! \brief Get a named value with type int, with default - //! \param name the name of the value to retrieve - //! \param defaultValue the default value if the name does not exist - //! \return the value retrieved on success or the default value - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Get a named value with type int, with default + /// \param name the name of the value to retrieve + /// \param defaultValue the default value if the name does not exist + /// \return the value retrieved on success or the default value + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() CRYPTOPP_DLL int GetIntValueWithDefault(const char *name, int defaultValue) const {return GetValueWithDefault(name, defaultValue);} - //! \brief Ensures an expected name and type is present - //! \param name the name of the value - //! \param stored the type that was stored for the name - //! \param retrieving the type that is being retrieved for the name - //! \throws ValueTypeMismatch - //! \details ThrowIfTypeMismatch() effectively performs a type safety check. - //! stored and retrieving are C++ mangled names for the type. - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Ensures an expected name and type is present + /// \param name the name of the value + /// \param stored the type that was stored for the name + /// \param retrieving the type that is being retrieved for the name + /// \throws ValueTypeMismatch + /// \details ThrowIfTypeMismatch() effectively performs a type safety check. + /// stored and retrieving are C++ mangled names for the type. + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() CRYPTOPP_DLL static void CRYPTOPP_API ThrowIfTypeMismatch(const char *name, const std::type_info &stored, const std::type_info &retrieving) {if (stored != retrieving) throw ValueTypeMismatch(name, stored, retrieving);} - //! \brief Retrieves a required name/value pair - //! \tparam T class or type - //! \param className the name of the class - //! \param name the name of the value - //! \param value reference to a variable to receive the value - //! \throws InvalidArgument - //! \details GetRequiredParameter() throws InvalidArgument if the name - //! is not present or not of the expected type T. - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Retrieves a required name/value pair + /// \tparam T class or type + /// \param className the name of the class + /// \param name the name of the value + /// \param value reference to a variable to receive the value + /// \throws InvalidArgument + /// \details GetRequiredParameter() throws InvalidArgument if the name + /// is not present or not of the expected type T. + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() template void GetRequiredParameter(const char *className, const char *name, T &value) const { @@ -426,44 +426,44 @@ public: throw InvalidArgument(std::string(className) + ": missing required parameter '" + name + "'"); } - //! \brief Retrieves a required name/value pair - //! \param className the name of the class - //! \param name the name of the value - //! \param value reference to a variable to receive the value - //! \throws InvalidArgument - //! \details GetRequiredParameter() throws InvalidArgument if the name - //! is not present or not of the expected type T. - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Retrieves a required name/value pair + /// \param className the name of the class + /// \param name the name of the value + /// \param value reference to a variable to receive the value + /// \throws InvalidArgument + /// \details GetRequiredParameter() throws InvalidArgument if the name + /// is not present or not of the expected type T. + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() CRYPTOPP_DLL void GetRequiredIntParameter(const char *className, const char *name, int &value) const { if (!GetIntValue(name, value)) throw InvalidArgument(std::string(className) + ": missing required parameter '" + name + "'"); } - //! \brief Get a named value - //! \param name the name of the object or value to retrieve - //! \param valueType reference to a variable that receives the value - //! \param pValue void pointer to a variable that receives the value - //! \returns true if the value was retrieved, false otherwise - //! \details GetVoidValue() retrieves the value of name if it exists. - //! \note GetVoidValue() is an internal function and should be implemented - //! by derived classes. Users should use one of the other functions instead. - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Get a named value + /// \param name the name of the object or value to retrieve + /// \param valueType reference to a variable that receives the value + /// \param pValue void pointer to a variable that receives the value + /// \returns true if the value was retrieved, false otherwise + /// \details GetVoidValue() retrieves the value of name if it exists. + /// \note GetVoidValue() is an internal function and should be implemented + /// by derived classes. Users should use one of the other functions instead. + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() CRYPTOPP_DLL virtual bool GetVoidValue(const char *name, const std::type_info &valueType, void *pValue) const =0; }; -//! \class NullNameValuePairs -//! \brief Interface for retrieving values given their names -//! \details This class is used when no names or values are present. Typically a program uses -//! g_nullNameValuePairs rather than creating its own NullNameValuePairs object. -//! \details NullNameValuePairs always existed in cryptlib.cpp. Crypto++ 6.0 moved NullNameValuePairs -//! into the header. This allowed the library to define g_nullNameValuePairs in the header rather -//! than declaring it as extern and placing the definition in the source file. As an external definition -//! the string g_nullNameValuePairs was subject to static initialization order fiasco problems. -//! \sa NameValuePairs, g_nullNameValuePairs, -//! NameValuePairs on the Crypto++ wiki +/// \class NullNameValuePairs +/// \brief Interface for retrieving values given their names +/// \details This class is used when no names or values are present. Typically a program uses +/// g_nullNameValuePairs rather than creating its own NullNameValuePairs object. +/// \details NullNameValuePairs always existed in cryptlib.cpp. Crypto++ 6.0 moved NullNameValuePairs +/// into the header. This allowed the library to define g_nullNameValuePairs in the header rather +/// than declaring it as extern and placing the definition in the source file. As an external definition +/// the string g_nullNameValuePairs was subject to static initialization order fiasco problems. +/// \sa NameValuePairs, g_nullNameValuePairs, +/// NameValuePairs on the Crypto++ wiki class NullNameValuePairs : public NameValuePairs { public: @@ -480,24 +480,24 @@ ANONYMOUS_NAMESPACE_END // Doxygen cannot handle initialization #if CRYPTOPP_DOXYGEN_PROCESSING -//! \brief Default channel for BufferedTransformation -//! \details DEFAULT_CHANNEL is equal to an empty string -//! \details Crypto++ 6.0 placed DEFAULT_CHANNEL in the header, rather than declaring it as extern and -//! placing the definition in the source file. As an external definition the string DEFAULT_CHANNEL -//! was subject to static initialization order fiasco problems. +/// \brief Default channel for BufferedTransformation +/// \details DEFAULT_CHANNEL is equal to an empty string +/// \details Crypto++ 6.0 placed DEFAULT_CHANNEL in the header, rather than declaring it as extern and +/// placing the definition in the source file. As an external definition the string DEFAULT_CHANNEL +/// was subject to static initialization order fiasco problems. const std::string DEFAULT_CHANNEL; -//! \brief Channel for additional authenticated data -//! \details AAD_CHANNEL is equal to "AAD" -//! \details Crypto++ 6.0 placed AAD_CHANNEL in the header, rather than declaring it as extern and -//! placing the definition in the source file. As an external definition the string AAD_CHANNEL -//! was subject to static initialization order fiasco problems. +/// \brief Channel for additional authenticated data +/// \details AAD_CHANNEL is equal to "AAD" +/// \details Crypto++ 6.0 placed AAD_CHANNEL in the header, rather than declaring it as extern and +/// placing the definition in the source file. As an external definition the string AAD_CHANNEL +/// was subject to static initialization order fiasco problems. const std::string AAD_CHANNEL; -//! \brief An empty set of name-value pairs -//! \details Crypto++ 6.0 placed g_nullNameValuePairs in the header, rather than declaring it as extern -//! and placing the definition in the source file. As an external definition the g_nullNameValuePairs -//! was subject to static initialization order fiasco problems. +/// \brief An empty set of name-value pairs +/// \details Crypto++ 6.0 placed g_nullNameValuePairs in the header, rather than declaring it as extern +/// and placing the definition in the source file. As an external definition the g_nullNameValuePairs +/// was subject to static initialization order fiasco problems. const NameValuePairs g_nullNameValuePairs; // Sun Studio 12.3 and earlier can't handle NameValuePairs initialization @@ -517,528 +517,528 @@ static const NameValuePairs& g_nullNameValuePairs(s_nullNameValuePairs); // Document additional name spaces which show up elsewhere in the sources. #if CRYPTOPP_DOXYGEN_PROCESSING -//! \brief Namespace containing value name definitions. -//! \details Name is part of the CryptoPP namespace. -//! \details The semantics of value names, types are: -//! 
-//!     ThisObject:ClassName (ClassName, copy of this object or a subobject)
-//!     ThisPointer:ClassName (const ClassName *, pointer to this object or a subobject)
-//!
+/// \brief Namespace containing value name definitions. +/// \details Name is part of the CryptoPP namespace. +/// \details The semantics of value names, types are: +/// 
+///     ThisObject:ClassName (ClassName, copy of this object or a subobject)
+///     ThisPointer:ClassName (const ClassName *, pointer to this object or a subobject)
+///
DOCUMENTED_NAMESPACE_BEGIN(Name) // more names defined in argnames.h DOCUMENTED_NAMESPACE_END -//! \brief Namespace containing weak and wounded algorithms. -//! \details Weak is part of the CryptoPP namespace. Schemes and algorithms are moved into Weak -//! when their security level is reduced to an unacceptable level by contemporary standards. -//! \details To use an algorithm in the Weak namespace, you must \c \#define -//! CRYPTOPP_ENABLE_NAMESPACE_WEAK 1 before including a header for a weak or wounded -//! algorithm. For example: -//! 
-//!     \c \#define CRYPTOPP_ENABLE_NAMESPACE_WEAK 1
-//!     \c \#include 
-//!     ...
-//!     CryptoPP::Weak::MD5 md5;
-//!
+/// \brief Namespace containing weak and wounded algorithms. +/// \details Weak is part of the CryptoPP namespace. Schemes and algorithms are moved into Weak +/// when their security level is reduced to an unacceptable level by contemporary standards. +/// \details To use an algorithm in the Weak namespace, you must \c \#define +/// CRYPTOPP_ENABLE_NAMESPACE_WEAK 1 before including a header for a weak or wounded +/// algorithm. For example: +/// 
+///     \c \#define CRYPTOPP_ENABLE_NAMESPACE_WEAK 1
+///     \c \#include 
+///     ...
+///     CryptoPP::Weak::MD5 md5;
+///
DOCUMENTED_NAMESPACE_BEGIN(Weak) // weak and wounded algorithms DOCUMENTED_NAMESPACE_END #endif -//! \brief Namespace containing testing and benchmark classes. -//! \details Source files for classes in the Test namespaces include -//! test.cpp, validat#.cpp and bench#.cpp. +/// \brief Namespace containing testing and benchmark classes. +/// \details Source files for classes in the Test namespaces include +/// test.cpp, validat#.cpp and bench#.cpp. DOCUMENTED_NAMESPACE_BEGIN(Test) // testing and benchmark classes DOCUMENTED_NAMESPACE_END // ******************************************************** -//! \class Clonable -//! \brief Interface for cloning objects -//! \note this is \a not implemented by most classes -//! \sa ClonableImpl, NotCopyable +/// \class Clonable +/// \brief Interface for cloning objects +/// \note this is \a not implemented by most classes +/// \sa ClonableImpl, NotCopyable class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Clonable { public: virtual ~Clonable() {} - //! \brief Copies this object - //! \return a copy of this object - //! \throws NotImplemented - //! \note this is \a not implemented by most classes - //! \sa NotCopyable + /// \brief Copies this object + /// \return a copy of this object + /// \throws NotImplemented + /// \note this is \a not implemented by most classes + /// \sa NotCopyable virtual Clonable* Clone() const {throw NotImplemented("Clone() is not implemented yet.");} // TODO: make this =0 }; -//! \class Algorithm -//! \brief Interface for all crypto algorithms +/// \class Algorithm +/// \brief Interface for all crypto algorithms class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Algorithm : public Clonable { public: virtual ~Algorithm() {} - //! \brief Interface for all crypto algorithms - //! \param checkSelfTestStatus determines whether the object can proceed if the self - //! tests have not been run or failed. - //! \details When FIPS 140-2 compliance is enabled and checkSelfTestStatus == true, - //! this constructor throws SelfTestFailure if the self test hasn't been run or fails. - //! \details FIPS 140-2 compliance is disabled by default. It is only used by certain - //! versions of the library when the library is built as a DLL on Windows. Also see - //! CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 in config.h. + /// \brief Interface for all crypto algorithms + /// \param checkSelfTestStatus determines whether the object can proceed if the self + /// tests have not been run or failed. + /// \details When FIPS 140-2 compliance is enabled and checkSelfTestStatus == true, + /// this constructor throws SelfTestFailure if the self test hasn't been run or fails. + /// \details FIPS 140-2 compliance is disabled by default. It is only used by certain + /// versions of the library when the library is built as a DLL on Windows. Also see + /// CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 in config.h. Algorithm(bool checkSelfTestStatus = true); - //! \brief Provides the name of this algorithm - //! \return the standard algorithm name - //! \details The standard algorithm name can be a name like \a AES or \a AES/GCM. Some algorithms - //! do not have standard names yet. For example, there is no standard algorithm name for - //! Shoup's ECIES. - //! \note AlgorithmName is not universally implemented yet + /// \brief Provides the name of this algorithm + /// \return the standard algorithm name + /// \details The standard algorithm name can be a name like \a AES or \a AES/GCM. Some algorithms + /// do not have standard names yet. For example, there is no standard algorithm name for + /// Shoup's ECIES. + /// \note AlgorithmName is not universally implemented yet virtual std::string AlgorithmName() const {return "unknown";} }; -//! \class SimpleKeyingInterface -//! \brief Interface for algorithms that take byte strings as keys -//! \sa FixedKeyLength(), VariableKeyLength(), SameKeyLengthAs(), SimpleKeyingInterfaceImpl() +/// \class SimpleKeyingInterface +/// \brief Interface for algorithms that take byte strings as keys +/// \sa FixedKeyLength(), VariableKeyLength(), SameKeyLengthAs(), SimpleKeyingInterfaceImpl() class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE SimpleKeyingInterface { public: virtual ~SimpleKeyingInterface() {} - //! \brief Returns smallest valid key length - //! \returns the minimum key length, in bytes + /// \brief Returns smallest valid key length + /// \returns the minimum key length, in bytes virtual size_t MinKeyLength() const =0; - //! \brief Returns largest valid key length - //! \returns the maximum key length, in bytes + /// \brief Returns largest valid key length + /// \returns the maximum key length, in bytes virtual size_t MaxKeyLength() const =0; - //! \brief Returns default key length - //! \returns the default (recommended) key length, in bytes + /// \brief Returns default key length + /// \returns the default (recommended) key length, in bytes virtual size_t DefaultKeyLength() const =0; - //! \brief Returns a valid key length for the algorithm - //! \param keylength the size of the key, in bytes - //! \returns the valid key length, in bytes - //! \details keylength is provided in bytes, not bits. If keylength is less than MIN_KEYLENGTH, - //! then the function returns MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, - //! then the function returns MAX_KEYLENGTH. if If keylength is a multiple of KEYLENGTH_MULTIPLE, - //! then keylength is returned. Otherwise, the function returns a \a lower multiple of - //! KEYLENGTH_MULTIPLE. + /// \brief Returns a valid key length for the algorithm + /// \param keylength the size of the key, in bytes + /// \returns the valid key length, in bytes + /// \details keylength is provided in bytes, not bits. If keylength is less than MIN_KEYLENGTH, + /// then the function returns MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, + /// then the function returns MAX_KEYLENGTH. if If keylength is a multiple of KEYLENGTH_MULTIPLE, + /// then keylength is returned. Otherwise, the function returns a \a lower multiple of + /// KEYLENGTH_MULTIPLE. virtual size_t GetValidKeyLength(size_t keylength) const =0; - //! \brief Returns whether keylength is a valid key length - //! \param keylength the requested keylength - //! \return true if keylength is valid, false otherwise - //! \details Internally the function calls GetValidKeyLength() + /// \brief Returns whether keylength is a valid key length + /// \param keylength the requested keylength + /// \return true if keylength is valid, false otherwise + /// \details Internally the function calls GetValidKeyLength() virtual bool IsValidKeyLength(size_t keylength) const {return keylength == GetValidKeyLength(keylength);} - //! \brief Sets or reset the key of this object - //! \param key the key to use when keying the object - //! \param length the size of the key, in bytes - //! \param params additional initialization parameters that cannot be passed - //! directly through the constructor + /// \brief Sets or reset the key of this object + /// \param key the key to use when keying the object + /// \param length the size of the key, in bytes + /// \param params additional initialization parameters that cannot be passed + /// directly through the constructor virtual void SetKey(const byte *key, size_t length, const NameValuePairs ¶ms = g_nullNameValuePairs); - //! \brief Sets or reset the key of this object - //! \param key the key to use when keying the object - //! \param length the size of the key, in bytes - //! \param rounds the number of rounds to apply the transformation function, - //! if applicable - //! \details SetKeyWithRounds() calls SetKey() with a NameValuePairs - //! object that only specifies rounds. rounds is an integer parameter, - //! and -1 means use the default number of rounds. + /// \brief Sets or reset the key of this object + /// \param key the key to use when keying the object + /// \param length the size of the key, in bytes + /// \param rounds the number of rounds to apply the transformation function, + /// if applicable + /// \details SetKeyWithRounds() calls SetKey() with a NameValuePairs + /// object that only specifies rounds. rounds is an integer parameter, + /// and -1 means use the default number of rounds. void SetKeyWithRounds(const byte *key, size_t length, int rounds); - //! \brief Sets or reset the key of this object - //! \param key the key to use when keying the object - //! \param length the size of the key, in bytes - //! \param iv the intiialization vector to use when keying the object - //! \param ivLength the size of the iv, in bytes - //! \details SetKeyWithIV() calls SetKey() with a NameValuePairs - //! that only specifies IV. The IV is a byte buffer with size ivLength. - //! ivLength is an integer parameter, and -1 means use IVSize(). + /// \brief Sets or reset the key of this object + /// \param key the key to use when keying the object + /// \param length the size of the key, in bytes + /// \param iv the intiialization vector to use when keying the object + /// \param ivLength the size of the iv, in bytes + /// \details SetKeyWithIV() calls SetKey() with a NameValuePairs + /// that only specifies IV. The IV is a byte buffer with size ivLength. + /// ivLength is an integer parameter, and -1 means use IVSize(). void SetKeyWithIV(const byte *key, size_t length, const byte *iv, size_t ivLength); - //! \brief Sets or reset the key of this object - //! \param key the key to use when keying the object - //! \param length the size of the key, in bytes - //! \param iv the intiialization vector to use when keying the object - //! \details SetKeyWithIV() calls SetKey() with a NameValuePairs() object - //! that only specifies iv. iv is a byte buffer, and it must have - //! a size IVSize(). + /// \brief Sets or reset the key of this object + /// \param key the key to use when keying the object + /// \param length the size of the key, in bytes + /// \param iv the intiialization vector to use when keying the object + /// \details SetKeyWithIV() calls SetKey() with a NameValuePairs() object + /// that only specifies iv. iv is a byte buffer, and it must have + /// a size IVSize(). void SetKeyWithIV(const byte *key, size_t length, const byte *iv) {SetKeyWithIV(key, length, iv, IVSize());} - //! \brief Secure IVs requirements as enumerated values. - //! \details Provides secure IV requirements as a monotonically increasing enumerated values. Requirements can be - //! compared using less than (<) and greater than (>). For example, UNIQUE_IV < RANDOM_IV - //! and UNPREDICTABLE_RANDOM_IV > RANDOM_IV. - //! \sa IsResynchronizable(), CanUseRandomIVs(), CanUsePredictableIVs(), CanUseStructuredIVs() + /// \brief Secure IVs requirements as enumerated values. + /// \details Provides secure IV requirements as a monotonically increasing enumerated values. Requirements can be + /// compared using less than (<) and greater than (>). For example, UNIQUE_IV < RANDOM_IV + /// and UNPREDICTABLE_RANDOM_IV > RANDOM_IV. + /// \sa IsResynchronizable(), CanUseRandomIVs(), CanUsePredictableIVs(), CanUseStructuredIVs() enum IV_Requirement { - //! \brief The IV must be unique + /// \brief The IV must be unique UNIQUE_IV = 0, - //! \brief The IV must be random and possibly predictable + /// \brief The IV must be random and possibly predictable RANDOM_IV, - //! \brief The IV must be random and unpredictable + /// \brief The IV must be random and unpredictable UNPREDICTABLE_RANDOM_IV, - //! \brief The IV is set by the object + /// \brief The IV is set by the object INTERNALLY_GENERATED_IV, - //! \brief The object does not use an IV + /// \brief The object does not use an IV NOT_RESYNCHRONIZABLE }; - //! \brief Minimal requirement for secure IVs - //! \return the secure IV requirement of the algorithm + /// \brief Minimal requirement for secure IVs + /// \return the secure IV requirement of the algorithm virtual IV_Requirement IVRequirement() const =0; - //! \brief Determines if the object can be resynchronized - //! \return true if the object can be resynchronized (i.e. supports initialization vectors), false otherwise - //! \note If this function returns true, and no IV is passed to SetKey() and CanUseStructuredIVs()==true, - //! an IV of all 0's will be assumed. + /// \brief Determines if the object can be resynchronized + /// \return true if the object can be resynchronized (i.e. supports initialization vectors), false otherwise + /// \note If this function returns true, and no IV is passed to SetKey() and CanUseStructuredIVs()==true, + /// an IV of all 0's will be assumed. bool IsResynchronizable() const {return IVRequirement() < NOT_RESYNCHRONIZABLE;} - //! \brief Determines if the object can use random IVs - //! \return true if the object can use random IVs (in addition to ones returned by GetNextIV), false otherwise + /// \brief Determines if the object can use random IVs + /// \return true if the object can use random IVs (in addition to ones returned by GetNextIV), false otherwise bool CanUseRandomIVs() const {return IVRequirement() <= UNPREDICTABLE_RANDOM_IV;} - //! \brief Determines if the object can use random but possibly predictable IVs - //! \return true if the object can use random but possibly predictable IVs (in addition to ones returned by - //! GetNextIV), false otherwise + /// \brief Determines if the object can use random but possibly predictable IVs + /// \return true if the object can use random but possibly predictable IVs (in addition to ones returned by + /// GetNextIV), false otherwise bool CanUsePredictableIVs() const {return IVRequirement() <= RANDOM_IV;} - //! \brief Determines if the object can use structured IVs - //! \returns true if the object can use structured IVs, false otherwise - //! \details CanUseStructuredIVs() indicates whether the object can use structured IVs; for example a counter - //! (in addition to ones returned by GetNextIV). + /// \brief Determines if the object can use structured IVs + /// \returns true if the object can use structured IVs, false otherwise + /// \details CanUseStructuredIVs() indicates whether the object can use structured IVs; for example a counter + /// (in addition to ones returned by GetNextIV). bool CanUseStructuredIVs() const {return IVRequirement() <= UNIQUE_IV;} - //! \brief Returns length of the IV accepted by this object - //! \return the size of an IV, in bytes - //! \throws NotImplemented() if the object does not support resynchronization - //! \details The default implementation throws NotImplemented + /// \brief Returns length of the IV accepted by this object + /// \return the size of an IV, in bytes + /// \throws NotImplemented() if the object does not support resynchronization + /// \details The default implementation throws NotImplemented virtual unsigned int IVSize() const {throw NotImplemented(GetAlgorithm().AlgorithmName() + ": this object doesn't support resynchronization");} - //! \brief Provides the default size of an IV - //! \return default length of IVs accepted by this object, in bytes + /// \brief Provides the default size of an IV + /// \return default length of IVs accepted by this object, in bytes unsigned int DefaultIVLength() const {return IVSize();} - //! \brief Provides the minimum size of an IV - //! \return minimal length of IVs accepted by this object, in bytes - //! \throws NotImplemented() if the object does not support resynchronization + /// \brief Provides the minimum size of an IV + /// \return minimal length of IVs accepted by this object, in bytes + /// \throws NotImplemented() if the object does not support resynchronization virtual unsigned int MinIVLength() const {return IVSize();} - //! \brief Provides the maximum size of an IV - //! \return maximal length of IVs accepted by this object, in bytes - //! \throws NotImplemented() if the object does not support resynchronization + /// \brief Provides the maximum size of an IV + /// \return maximal length of IVs accepted by this object, in bytes + /// \throws NotImplemented() if the object does not support resynchronization virtual unsigned int MaxIVLength() const {return IVSize();} - //! \brief Resynchronize with an IV - //! \param iv the initialization vector - //! \param ivLength the size of the initialization vector, in bytes - //! \details Resynchronize() resynchronizes with an IV provided by the caller. ivLength=-1 means use IVSize(). - //! \throws NotImplemented() if the object does not support resynchronization + /// \brief Resynchronize with an IV + /// \param iv the initialization vector + /// \param ivLength the size of the initialization vector, in bytes + /// \details Resynchronize() resynchronizes with an IV provided by the caller. ivLength=-1 means use IVSize(). + /// \throws NotImplemented() if the object does not support resynchronization virtual void Resynchronize(const byte *iv, int ivLength=-1) { CRYPTOPP_UNUSED(iv); CRYPTOPP_UNUSED(ivLength); throw NotImplemented(GetAlgorithm().AlgorithmName() + ": this object doesn't support resynchronization"); } - //! \brief Retrieves a secure IV for the next message - //! \param rng a RandomNumberGenerator to produce keying material - //! \param iv a block of bytes to receive the IV - //! \details The IV must be at least IVSize() in length. - //! \details This method should be called after you finish encrypting one message and are ready - //! to start the next one. After calling it, you must call SetKey() or Resynchronize(). - //! before using this object again. - //! \details Internally, the base class implementation calls RandomNumberGenerator's GenerateBlock() - //! \note This method is not implemented on decryption objects. + /// \brief Retrieves a secure IV for the next message + /// \param rng a RandomNumberGenerator to produce keying material + /// \param iv a block of bytes to receive the IV + /// \details The IV must be at least IVSize() in length. + /// \details This method should be called after you finish encrypting one message and are ready + /// to start the next one. After calling it, you must call SetKey() or Resynchronize(). + /// before using this object again. + /// \details Internally, the base class implementation calls RandomNumberGenerator's GenerateBlock() + /// \note This method is not implemented on decryption objects. virtual void GetNextIV(RandomNumberGenerator &rng, byte *iv); protected: - //! \brief Returns the base class Algorithm - //! \return the base class Algorithm + /// \brief Returns the base class Algorithm + /// \return the base class Algorithm virtual const Algorithm & GetAlgorithm() const =0; - //! \brief Sets the key for this object without performing parameter validation - //! \param key a byte buffer used to key the cipher - //! \param length the length of the byte buffer - //! \param params additional parameters passed as NameValuePairs - //! \details key must be at least DEFAULT_KEYLENGTH in length. + /// \brief Sets the key for this object without performing parameter validation + /// \param key a byte buffer used to key the cipher + /// \param length the length of the byte buffer + /// \param params additional parameters passed as NameValuePairs + /// \details key must be at least DEFAULT_KEYLENGTH in length. virtual void UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs ¶ms) =0; - //! \brief Validates the key length - //! \param length the size of the keying material, in bytes - //! \throws InvalidKeyLength if the key length is invalid + /// \brief Validates the key length + /// \param length the size of the keying material, in bytes + /// \throws InvalidKeyLength if the key length is invalid void ThrowIfInvalidKeyLength(size_t length); - //! \brief Validates the object - //! \throws InvalidArgument if the IV is present - //! \details Internally, the default implementation calls IsResynchronizable() and throws - //! InvalidArgument if the function returns true. - //! \note called when no IV is passed + /// \brief Validates the object + /// \throws InvalidArgument if the IV is present + /// \details Internally, the default implementation calls IsResynchronizable() and throws + /// InvalidArgument if the function returns true. + /// \note called when no IV is passed void ThrowIfResynchronizable(); - //! \brief Validates the IV - //! \param iv the IV with a length of IVSize, in bytes - //! \throws InvalidArgument on failure - //! \details Internally, the default implementation checks the iv. If iv is not NULL or nullptr, - //! then the function succeeds. If iv is NULL, then IVRequirement is checked against - //! UNPREDICTABLE_RANDOM_IV. If IVRequirement is UNPREDICTABLE_RANDOM_IV, then - //! then the function succeeds. Otherwise, an exception is thrown. + /// \brief Validates the IV + /// \param iv the IV with a length of IVSize, in bytes + /// \throws InvalidArgument on failure + /// \details Internally, the default implementation checks the iv. If iv is not NULL or nullptr, + /// then the function succeeds. If iv is NULL, then IVRequirement is checked against + /// UNPREDICTABLE_RANDOM_IV. If IVRequirement is UNPREDICTABLE_RANDOM_IV, then + /// then the function succeeds. Otherwise, an exception is thrown. void ThrowIfInvalidIV(const byte *iv); - //! \brief Validates the IV length - //! \param length the size of an IV, in bytes - //! \throws InvalidArgument if the IV length is invalid + /// \brief Validates the IV length + /// \param length the size of an IV, in bytes + /// \throws InvalidArgument if the IV length is invalid size_t ThrowIfInvalidIVLength(int length); - //! \brief Retrieves and validates the IV - //! \param params NameValuePairs with the IV supplied as a ConstByteArrayParameter - //! \param size the length of the IV, in bytes - //! \return a pointer to the first byte of the IV - //! \throws InvalidArgument if the number of rounds are invalid + /// \brief Retrieves and validates the IV + /// \param params NameValuePairs with the IV supplied as a ConstByteArrayParameter + /// \param size the length of the IV, in bytes + /// \return a pointer to the first byte of the IV + /// \throws InvalidArgument if the number of rounds are invalid const byte * GetIVAndThrowIfInvalid(const NameValuePairs ¶ms, size_t &size); - //! \brief Validates the key length - //! \param length the size of the keying material, in bytes + /// \brief Validates the key length + /// \param length the size of the keying material, in bytes inline void AssertValidKeyLength(size_t length) const {CRYPTOPP_UNUSED(length); CRYPTOPP_ASSERT(IsValidKeyLength(length));} }; -//! \brief Interface for the data processing part of block ciphers -//! \details Classes derived from BlockTransformation are block ciphers -//! in ECB mode (for example the DES::Encryption class), which are stateless. -//! These classes should not be used directly, but only in combination with -//! a mode class (see CipherModeDocumentation in modes.h). +/// \brief Interface for the data processing part of block ciphers +/// \details Classes derived from BlockTransformation are block ciphers +/// in ECB mode (for example the DES::Encryption class), which are stateless. +/// These classes should not be used directly, but only in combination with +/// a mode class (see CipherModeDocumentation in modes.h). class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE BlockTransformation : public Algorithm { public: virtual ~BlockTransformation() {} - //! \brief Encrypt or decrypt a block - //! \param inBlock the input message before processing - //! \param outBlock the output message after processing - //! \param xorBlock an optional XOR mask - //! \details ProcessAndXorBlock encrypts or decrypts inBlock, xor with xorBlock, and write to outBlock. - //! \details The size of the block is determined by the block cipher and its documentation. Use - //! BLOCKSIZE at compile time, or BlockSize() at runtime. - //! \note The message can be transformed in-place, or the buffers must \a not overlap - //! \sa FixedBlockSize, BlockCipherFinal from seckey.h and BlockSize() + /// \brief Encrypt or decrypt a block + /// \param inBlock the input message before processing + /// \param outBlock the output message after processing + /// \param xorBlock an optional XOR mask + /// \details ProcessAndXorBlock encrypts or decrypts inBlock, xor with xorBlock, and write to outBlock. + /// \details The size of the block is determined by the block cipher and its documentation. Use + /// BLOCKSIZE at compile time, or BlockSize() at runtime. + /// \note The message can be transformed in-place, or the buffers must \a not overlap + /// \sa FixedBlockSize, BlockCipherFinal from seckey.h and BlockSize() virtual void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const =0; - //! \brief Encrypt or decrypt a block - //! \param inBlock the input message before processing - //! \param outBlock the output message after processing - //! \details ProcessBlock encrypts or decrypts inBlock and write to outBlock. - //! \details The size of the block is determined by the block cipher and its documentation. - //! Use BLOCKSIZE at compile time, or BlockSize() at runtime. - //! \sa FixedBlockSize, BlockCipherFinal from seckey.h and BlockSize() - //! \note The message can be transformed in-place, or the buffers must \a not overlap + /// \brief Encrypt or decrypt a block + /// \param inBlock the input message before processing + /// \param outBlock the output message after processing + /// \details ProcessBlock encrypts or decrypts inBlock and write to outBlock. + /// \details The size of the block is determined by the block cipher and its documentation. + /// Use BLOCKSIZE at compile time, or BlockSize() at runtime. + /// \sa FixedBlockSize, BlockCipherFinal from seckey.h and BlockSize() + /// \note The message can be transformed in-place, or the buffers must \a not overlap void ProcessBlock(const byte *inBlock, byte *outBlock) const {ProcessAndXorBlock(inBlock, NULLPTR, outBlock);} - //! \brief Encrypt or decrypt a block in place - //! \param inoutBlock the input message before processing - //! \details ProcessBlock encrypts or decrypts inoutBlock in-place. - //! \details The size of the block is determined by the block cipher and its documentation. - //! Use BLOCKSIZE at compile time, or BlockSize() at runtime. - //! \sa FixedBlockSize, BlockCipherFinal from seckey.h and BlockSize() + /// \brief Encrypt or decrypt a block in place + /// \param inoutBlock the input message before processing + /// \details ProcessBlock encrypts or decrypts inoutBlock in-place. + /// \details The size of the block is determined by the block cipher and its documentation. + /// Use BLOCKSIZE at compile time, or BlockSize() at runtime. + /// \sa FixedBlockSize, BlockCipherFinal from seckey.h and BlockSize() void ProcessBlock(byte *inoutBlock) const {ProcessAndXorBlock(inoutBlock, NULLPTR, inoutBlock);} - //! Provides the block size of the cipher - //! \return the block size of the cipher, in bytes + /// Provides the block size of the cipher + /// \return the block size of the cipher, in bytes virtual unsigned int BlockSize() const =0; - //! \brief Provides input and output data alignment for optimal performance. - //! \return the input data alignment that provides optimal performance + /// \brief Provides input and output data alignment for optimal performance. + /// \return the input data alignment that provides optimal performance virtual unsigned int OptimalDataAlignment() const; - //! returns true if this is a permutation (i.e. there is an inverse transformation) + /// returns true if this is a permutation (i.e. there is an inverse transformation) virtual bool IsPermutation() const {return true;} - //! \brief Determines if the cipher is being operated in its forward direction - //! \returns true if DIR is ENCRYPTION, false otherwise - //! \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection() + /// \brief Determines if the cipher is being operated in its forward direction + /// \returns true if DIR is ENCRYPTION, false otherwise + /// \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection() virtual bool IsForwardTransformation() const =0; - //! \brief Determines the number of blocks that can be processed in parallel - //! \return the number of blocks that can be processed in parallel, for bit-slicing implementations - //! \details Bit-slicing is often used to improve throughput and minimize timing attacks. + /// \brief Determines the number of blocks that can be processed in parallel + /// \return the number of blocks that can be processed in parallel, for bit-slicing implementations + /// \details Bit-slicing is often used to improve throughput and minimize timing attacks. virtual unsigned int OptimalNumberOfParallelBlocks() const {return 1;} - //! \brief Bit flags that control AdvancedProcessBlocks() behavior + /// \brief Bit flags that control AdvancedProcessBlocks() behavior enum FlagsForAdvancedProcessBlocks { - //! \brief inBlock is a counter + /// \brief inBlock is a counter BT_InBlockIsCounter=1, - //! \brief should not modify block pointers + /// \brief should not modify block pointers BT_DontIncrementInOutPointers=2, - //! \brief Xor inputs before transformation + /// \brief Xor inputs before transformation BT_XorInput=4, - //! \brief perform the transformation in reverse + /// \brief perform the transformation in reverse BT_ReverseDirection=8, - //! \brief Allow parallel transformations + /// \brief Allow parallel transformations BT_AllowParallel=16}; - //! \brief Encrypt and xor multiple blocks using additional flags - //! \param inBlocks the input message before processing - //! \param xorBlocks an optional XOR mask - //! \param outBlocks the output message after processing - //! \param length the size of the blocks, in bytes - //! \param flags additional flags to control processing - //! \details Encrypt and xor multiple blocks according to FlagsForAdvancedProcessBlocks flags. - //! \note If BT_InBlockIsCounter is set, then the last byte of inBlocks may be modified. + /// \brief Encrypt and xor multiple blocks using additional flags + /// \param inBlocks the input message before processing + /// \param xorBlocks an optional XOR mask + /// \param outBlocks the output message after processing + /// \param length the size of the blocks, in bytes + /// \param flags additional flags to control processing + /// \details Encrypt and xor multiple blocks according to FlagsForAdvancedProcessBlocks flags. + /// \note If BT_InBlockIsCounter is set, then the last byte of inBlocks may be modified. virtual size_t AdvancedProcessBlocks(const byte *inBlocks, const byte *xorBlocks, byte *outBlocks, size_t length, word32 flags) const; - //! \brief Provides the direction of the cipher - //! \return ENCRYPTION if IsForwardTransformation() is true, DECRYPTION otherwise - //! \sa IsForwardTransformation(), IsPermutation() + /// \brief Provides the direction of the cipher + /// \return ENCRYPTION if IsForwardTransformation() is true, DECRYPTION otherwise + /// \sa IsForwardTransformation(), IsPermutation() inline CipherDir GetCipherDirection() const {return IsForwardTransformation() ? ENCRYPTION : DECRYPTION;} }; -//! \class StreamTransformation -//! \brief Interface for the data processing portion of stream ciphers -//! \sa StreamTransformationFilter() +/// \class StreamTransformation +/// \brief Interface for the data processing portion of stream ciphers +/// \sa StreamTransformationFilter() class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE StreamTransformation : public Algorithm { public: virtual ~StreamTransformation() {} - //! \brief Provides a reference to this object - //! \return A reference to this object - //! \details Useful for passing a temporary object to a function that takes a non-const reference + /// \brief Provides a reference to this object + /// \return A reference to this object + /// \details Useful for passing a temporary object to a function that takes a non-const reference StreamTransformation& Ref() {return *this;} - //! \brief Provides the mandatory block size of the cipher - //! \return The block size of the cipher if input must be processed in blocks, 1 otherwise - //! \details Stream ciphers and some block ciphers modes of operation return 1. Modes that - //! return 1 must be able to process a single byte at a time, like counter mode. If a - //! mode of operation or block cipher cannot stream then it must not return 1. - //! \details When filters operate the mode or cipher, ProcessData will be called with a - //! string of bytes that is determined by MandatoryBlockSize and OptimalBlockSize. When a - //! policy is set, like 16-byte strings for a 16-byte block cipher, the filter will buffer - //! bytes until the specified number of bytes is available to the object. - //! \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial + /// \brief Provides the mandatory block size of the cipher + /// \return The block size of the cipher if input must be processed in blocks, 1 otherwise + /// \details Stream ciphers and some block ciphers modes of operation return 1. Modes that + /// return 1 must be able to process a single byte at a time, like counter mode. If a + /// mode of operation or block cipher cannot stream then it must not return 1. + /// \details When filters operate the mode or cipher, ProcessData will be called with a + /// string of bytes that is determined by MandatoryBlockSize and OptimalBlockSize. When a + /// policy is set, like 16-byte strings for a 16-byte block cipher, the filter will buffer + /// bytes until the specified number of bytes is available to the object. + /// \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial virtual unsigned int MandatoryBlockSize() const {return 1;} - //! \brief Provides the input block size most efficient for this cipher - //! \return The input block size that is most efficient for the cipher - //! \details The base class implementation returns MandatoryBlockSize(). - //! \note Optimal input length is - //! n * OptimalBlockSize() - GetOptimalBlockSizeUsed() for any n \> 0. + /// \brief Provides the input block size most efficient for this cipher + /// \return The input block size that is most efficient for the cipher + /// \details The base class implementation returns MandatoryBlockSize(). + /// \note Optimal input length is + /// n * OptimalBlockSize() - GetOptimalBlockSizeUsed() for any n \> 0. virtual unsigned int OptimalBlockSize() const {return MandatoryBlockSize();} - //! \brief Provides the number of bytes used in the current block when processing at optimal block size. - //! \return the number of bytes used in the current block when processing at the optimal block size + /// \brief Provides the number of bytes used in the current block when processing at optimal block size. + /// \return the number of bytes used in the current block when processing at the optimal block size virtual unsigned int GetOptimalBlockSizeUsed() const {return 0;} - //! \brief Provides input and output data alignment for optimal performance - //! \return the input data alignment that provides optimal performance + /// \brief Provides input and output data alignment for optimal performance + /// \return the input data alignment that provides optimal performance virtual unsigned int OptimalDataAlignment() const; - //! \brief Encrypt or decrypt an array of bytes - //! \param outString the output byte buffer - //! \param inString the input byte buffer - //! \param length the size of the input and output byte buffers, in bytes - //! \details ProcessData is called with a string of bytes whose size depends on MandatoryBlockSize. - //! Either inString == outString, or they must not overlap. - //! \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial + /// \brief Encrypt or decrypt an array of bytes + /// \param outString the output byte buffer + /// \param inString the input byte buffer + /// \param length the size of the input and output byte buffers, in bytes + /// \details ProcessData is called with a string of bytes whose size depends on MandatoryBlockSize. + /// Either inString == outString, or they must not overlap. + /// \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial virtual void ProcessData(byte *outString, const byte *inString, size_t length) =0; - //! \brief Encrypt or decrypt the last block of data - //! \param outString the output byte buffer - //! \param outLength the size of the output byte buffer, in bytes - //! \param inString the input byte buffer - //! \param inLength the size of the input byte buffer, in bytes - //! \returns the number of bytes used in outString - //! \details ProcessLastBlock is used when the last block of data is special and requires handling - //! by the cipher. The current implementation provides an output buffer with a size - //! inLength+2*MandatoryBlockSize(). The return value allows the cipher to expand cipher - //! text during encryption or shrink plain text during decryption. - //! \details This member function is used by CBC-CTS and OCB modes. - //! \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial + /// \brief Encrypt or decrypt the last block of data + /// \param outString the output byte buffer + /// \param outLength the size of the output byte buffer, in bytes + /// \param inString the input byte buffer + /// \param inLength the size of the input byte buffer, in bytes + /// \returns the number of bytes used in outString + /// \details ProcessLastBlock is used when the last block of data is special and requires handling + /// by the cipher. The current implementation provides an output buffer with a size + /// inLength+2*MandatoryBlockSize(). The return value allows the cipher to expand cipher + /// text during encryption or shrink plain text during decryption. + /// \details This member function is used by CBC-CTS and OCB modes. + /// \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial virtual size_t ProcessLastBlock(byte *outString, size_t outLength, const byte *inString, size_t inLength); - //! \brief Provides the size of the last block - //! \returns the minimum size of the last block - //! \details MinLastBlockSize() returns the minimum size of the last block. 0 indicates the last - //! block is not special. - //! \details MandatoryBlockSize() enlists one of two behaviors. First, if MandatoryBlockSize() - //! returns 1, then the cipher can be streamed and ProcessData() is called with the tail bytes. - //! Second, if MandatoryBlockSize() returns non-0, then the string of bytes is padded to - //! MandatoryBlockSize() according to the padding mode. Then, ProcessData() is called with the - //! padded string of bytes. - //! \details Some authenticated encryption modes are not expressed well with MandatoryBlockSize() - //! and MinLastBlockSize(). For example, AES/OCB uses 16-byte blocks (MandatoryBlockSize = 16) - //! and the last block requires special processing (MinLastBlockSize = 0). However, 0 is a valid - //! last block size for OCB and the special processing is custom padding, and not standard PKCS - //! padding. In response an unambiguous IsLastBlockSpecial() was added. - //! \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial + /// \brief Provides the size of the last block + /// \returns the minimum size of the last block + /// \details MinLastBlockSize() returns the minimum size of the last block. 0 indicates the last + /// block is not special. + /// \details MandatoryBlockSize() enlists one of two behaviors. First, if MandatoryBlockSize() + /// returns 1, then the cipher can be streamed and ProcessData() is called with the tail bytes. + /// Second, if MandatoryBlockSize() returns non-0, then the string of bytes is padded to + /// MandatoryBlockSize() according to the padding mode. Then, ProcessData() is called with the + /// padded string of bytes. + /// \details Some authenticated encryption modes are not expressed well with MandatoryBlockSize() + /// and MinLastBlockSize(). For example, AES/OCB uses 16-byte blocks (MandatoryBlockSize = 16) + /// and the last block requires special processing (MinLastBlockSize = 0). However, 0 is a valid + /// last block size for OCB and the special processing is custom padding, and not standard PKCS + /// padding. In response an unambiguous IsLastBlockSpecial() was added. + /// \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial virtual unsigned int MinLastBlockSize() const {return 0;} - //! \brief Determines if the last block receives special processing - //! \returns true if the last block reveives special processing, false otherwise. - //! \details Some authenticated encryption modes are not expressed well with - //! MandatoryBlockSize() and MinLastBlockSize(). For example, AES/OCB uses - //! 16-byte blocks (MandatoryBlockSize = 16) and the last block requires special processing - //! (MinLastBlockSize = 0). However, 0 is a valid last block size for OCB and the special - //! processing is custom padding, and not standard PKCS padding. In response an - //! unambiguous IsLastBlockSpecial() was added. - //! \details When IsLastBlockSpecial() returns false nothing special happens. All the former - //! rules and behaviors apply. This is the default behavior of IsLastBlockSpecial(). - //! \details When IsLastBlockSpecial() returns true four things happen. First, MinLastBlockSize = 0 - //! means 0 is a valid block size that should be processed. Second, standard block cipher padding is - //! \a not \a applied. Third, the caller supplies an outString is larger than inString by - //! 2*MandatoryBlockSize(). That is, there's a reserve available when processing the last block. - //! Fourth, the cipher is responsible for finalization like custom padding. The cipher will tell - //! the library how many bytes were processed or used by returning the appropriate value from - //! ProcessLastBlock(). - //! \details The return value of ProcessLastBlock() indicates how many bytes were written to - //! outString. A filter pipelining data will send outString and up to outLength - //! to an AttachedTransformation() for additional processing. Below is an example of the code - //! used in StreamTransformationFilter::LastPut. - //! 
  if (m_cipher.IsLastBlockSpecial())
-	//!   {
-	//!     size_t reserve = 2*m_cipher.MandatoryBlockSize();
-	//!     space = HelpCreatePutSpace(*AttachedTransformation(), DEFAULT_CHANNEL, length+reserve);
-	//!     length = m_cipher.ProcessLastBlock(space, length+reserve, inString, length);
-	//!     AttachedTransformation()->Put(space, length);
-	//!     return;
-	//!   }
- //! \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial - //! \since Crypto++ 6.0 + /// \brief Determines if the last block receives special processing + /// \returns true if the last block reveives special processing, false otherwise. + /// \details Some authenticated encryption modes are not expressed well with + /// MandatoryBlockSize() and MinLastBlockSize(). For example, AES/OCB uses + /// 16-byte blocks (MandatoryBlockSize = 16) and the last block requires special processing + /// (MinLastBlockSize = 0). However, 0 is a valid last block size for OCB and the special + /// processing is custom padding, and not standard PKCS padding. In response an + /// unambiguous IsLastBlockSpecial() was added. + /// \details When IsLastBlockSpecial() returns false nothing special happens. All the former + /// rules and behaviors apply. This is the default behavior of IsLastBlockSpecial(). + /// \details When IsLastBlockSpecial() returns true four things happen. First, MinLastBlockSize = 0 + /// means 0 is a valid block size that should be processed. Second, standard block cipher padding is + /// \a not \a applied. Third, the caller supplies an outString is larger than inString by + /// 2*MandatoryBlockSize(). That is, there's a reserve available when processing the last block. + /// Fourth, the cipher is responsible for finalization like custom padding. The cipher will tell + /// the library how many bytes were processed or used by returning the appropriate value from + /// ProcessLastBlock(). + /// \details The return value of ProcessLastBlock() indicates how many bytes were written to + /// outString. A filter pipelining data will send outString and up to outLength + /// to an AttachedTransformation() for additional processing. Below is an example of the code + /// used in StreamTransformationFilter::LastPut. + /// 
  if (m_cipher.IsLastBlockSpecial())
+	///   {
+	///     size_t reserve = 2*m_cipher.MandatoryBlockSize();
+	///     space = HelpCreatePutSpace(*AttachedTransformation(), DEFAULT_CHANNEL, length+reserve);
+	///     length = m_cipher.ProcessLastBlock(space, length+reserve, inString, length);
+	///     AttachedTransformation()->Put(space, length);
+	///     return;
+	///   }
+ /// \sa ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial + /// \since Crypto++ 6.0 virtual bool IsLastBlockSpecial() const {return false;} - //! \brief Encrypt or decrypt a string of bytes - //! \param inoutString the string to process - //! \param length the size of the inoutString, in bytes - //! \details Internally, the base class implementation calls ProcessData(). + /// \brief Encrypt or decrypt a string of bytes + /// \param inoutString the string to process + /// \param length the size of the inoutString, in bytes + /// \details Internally, the base class implementation calls ProcessData(). inline void ProcessString(byte *inoutString, size_t length) {ProcessData(inoutString, inoutString, length);} - //! \brief Encrypt or decrypt a string of bytes - //! \param outString the output string to process - //! \param inString the input string to process - //! \param length the size of the input and output strings, in bytes - //! \details Internally, the base class implementation calls ProcessData(). + /// \brief Encrypt or decrypt a string of bytes + /// \param outString the output string to process + /// \param inString the input string to process + /// \param length the size of the input and output strings, in bytes + /// \details Internally, the base class implementation calls ProcessData(). inline void ProcessString(byte *outString, const byte *inString, size_t length) {ProcessData(outString, inString, length);} - //! \brief Encrypt or decrypt a byte - //! \param input the input byte to process - //! \details Internally, the base class implementation calls ProcessData() with a size of 1. + /// \brief Encrypt or decrypt a byte + /// \param input the input byte to process + /// \details Internally, the base class implementation calls ProcessData() with a size of 1. inline byte ProcessByte(byte input) {ProcessData(&input, &input, 1); return input;} - //! \brief Determines whether the cipher supports random access - //! \returns true if the cipher supports random access, false otherwise + /// \brief Determines whether the cipher supports random access + /// \returns true if the cipher supports random access, false otherwise virtual bool IsRandomAccess() const =0; - //! \brief Seek to an absolute position - //! \param pos position to seek - //! \throws NotImplemented - //! \details The base class implementation throws NotImplemented. The function - //! \ref CRYPTOPP_ASSERT "asserts" IsRandomAccess() in debug builds. + /// \brief Seek to an absolute position + /// \param pos position to seek + /// \throws NotImplemented + /// \details The base class implementation throws NotImplemented. The function + /// \ref CRYPTOPP_ASSERT "asserts" IsRandomAccess() in debug builds. virtual void Seek(lword pos) { CRYPTOPP_UNUSED(pos); @@ -1046,236 +1046,236 @@ public: throw NotImplemented("StreamTransformation: this object doesn't support random access"); } - //! \brief Determines whether the cipher is self-inverting - //! \returns true if the cipher is self-inverting, false otherwise - //! \details IsSelfInverting determines whether this transformation is - //! self-inverting (e.g. xor with a keystream). + /// \brief Determines whether the cipher is self-inverting + /// \returns true if the cipher is self-inverting, false otherwise + /// \details IsSelfInverting determines whether this transformation is + /// self-inverting (e.g. xor with a keystream). virtual bool IsSelfInverting() const =0; - //! \brief Determines if the cipher is being operated in its forward direction - //! \returns true if DIR is ENCRYPTION, false otherwise - //! \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection() + /// \brief Determines if the cipher is being operated in its forward direction + /// \returns true if DIR is ENCRYPTION, false otherwise + /// \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection() virtual bool IsForwardTransformation() const =0; }; -//! \class HashTransformation -//! \brief Interface for hash functions and data processing part of MACs -//! \details HashTransformation objects are stateful. They are created in an initial state, -//! change state as Update() is called, and return to the initial -//! state when Final() is called. This interface allows a large message to -//! be hashed in pieces by calling Update() on each piece followed by -//! calling Final(). -//! \sa HashFilter(), HashVerificationFilter() +/// \class HashTransformation +/// \brief Interface for hash functions and data processing part of MACs +/// \details HashTransformation objects are stateful. They are created in an initial state, +/// change state as Update() is called, and return to the initial +/// state when Final() is called. This interface allows a large message to +/// be hashed in pieces by calling Update() on each piece followed by +/// calling Final(). +/// \sa HashFilter(), HashVerificationFilter() class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE HashTransformation : public Algorithm { public: virtual ~HashTransformation() {} - //! \brief Provides a reference to this object - //! \return A reference to this object - //! \details Useful for passing a temporary object to a function that takes a non-const reference + /// \brief Provides a reference to this object + /// \return A reference to this object + /// \details Useful for passing a temporary object to a function that takes a non-const reference HashTransformation& Ref() {return *this;} - //! \brief Updates a hash with additional input - //! \param input the additional input as a buffer - //! \param length the size of the buffer, in bytes + /// \brief Updates a hash with additional input + /// \param input the additional input as a buffer + /// \param length the size of the buffer, in bytes virtual void Update(const byte *input, size_t length) =0; - //! \brief Request space which can be written into by the caller - //! \param size the requested size of the buffer - //! \details The purpose of this method is to help avoid extra memory allocations. - //! \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, - //! size is the requested size of the buffer. When the call returns, size is the size of - //! the array returned to the caller. - //! \details The base class implementation sets size to 0 and returns NULL or nullptr. - //! \note Some objects, like ArraySink, cannot create a space because its fixed. + /// \brief Request space which can be written into by the caller + /// \param size the requested size of the buffer + /// \details The purpose of this method is to help avoid extra memory allocations. + /// \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, + /// size is the requested size of the buffer. When the call returns, size is the size of + /// the array returned to the caller. + /// \details The base class implementation sets size to 0 and returns NULL or nullptr. + /// \note Some objects, like ArraySink, cannot create a space because its fixed. virtual byte * CreateUpdateSpace(size_t &size) {size=0; return NULLPTR;} - //! \brief Computes the hash of the current message - //! \param digest a pointer to the buffer to receive the hash - //! \details Final() restarts the hash for a new message. - //! \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures - //! the output byte buffer is large enough for the digest. + /// \brief Computes the hash of the current message + /// \param digest a pointer to the buffer to receive the hash + /// \details Final() restarts the hash for a new message. + /// \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures + /// the output byte buffer is large enough for the digest. virtual void Final(byte *digest) {TruncatedFinal(digest, DigestSize());} - //! \brief Restart the hash - //! \details Discards the current state, and restart for a new message + /// \brief Restart the hash + /// \details Discards the current state, and restart for a new message virtual void Restart() {TruncatedFinal(NULLPTR, 0);} - //! Provides the digest size of the hash - //! \return the digest size of the hash. + /// Provides the digest size of the hash + /// \return the digest size of the hash. virtual unsigned int DigestSize() const =0; - //! Provides the tag size of the hash - //! \return the tag size of the hash. - //! \details Same as DigestSize(). + /// Provides the tag size of the hash + /// \return the tag size of the hash. + /// \details Same as DigestSize(). unsigned int TagSize() const {return DigestSize();} - //! \brief Provides the block size of the compression function - //! \return the block size of the compression function, in bytes - //! \details BlockSize() will return 0 if the hash is not block based. For example, - //! SHA3 is a recursive hash (not an iterative hash), and it does not have a block size. + /// \brief Provides the block size of the compression function + /// \return the block size of the compression function, in bytes + /// \details BlockSize() will return 0 if the hash is not block based. For example, + /// SHA3 is a recursive hash (not an iterative hash), and it does not have a block size. virtual unsigned int BlockSize() const {return 0;} - //! \brief Provides the input block size most efficient for this hash. - //! \return The input block size that is most efficient for the cipher - //! \details The base class implementation returns MandatoryBlockSize(). - //! \details Optimal input length is - //! n * OptimalBlockSize() - GetOptimalBlockSizeUsed() for any n \> 0. + /// \brief Provides the input block size most efficient for this hash. + /// \return The input block size that is most efficient for the cipher + /// \details The base class implementation returns MandatoryBlockSize(). + /// \details Optimal input length is + /// n * OptimalBlockSize() - GetOptimalBlockSizeUsed() for any n \> 0. virtual unsigned int OptimalBlockSize() const {return 1;} - //! \brief Provides input and output data alignment for optimal performance - //! \return the input data alignment that provides optimal performance + /// \brief Provides input and output data alignment for optimal performance + /// \return the input data alignment that provides optimal performance virtual unsigned int OptimalDataAlignment() const; - //! \brief Updates the hash with additional input and computes the hash of the current message - //! \param digest a pointer to the buffer to receive the hash - //! \param input the additional input as a buffer - //! \param length the size of the buffer, in bytes - //! \details Use this if your input is in one piece and you don't want to call Update() - //! and Final() separately - //! \details CalculateDigest() restarts the hash for the next message. - //! \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures - //! the output byte buffer is large enough for the digest. + /// \brief Updates the hash with additional input and computes the hash of the current message + /// \param digest a pointer to the buffer to receive the hash + /// \param input the additional input as a buffer + /// \param length the size of the buffer, in bytes + /// \details Use this if your input is in one piece and you don't want to call Update() + /// and Final() separately + /// \details CalculateDigest() restarts the hash for the next message. + /// \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures + /// the output byte buffer is large enough for the digest. virtual void CalculateDigest(byte *digest, const byte *input, size_t length) {Update(input, length); Final(digest);} - //! \brief Verifies the hash of the current message - //! \param digest a pointer to the buffer of an \a existing hash - //! \return \p true if the existing hash matches the computed hash, \p false otherwise - //! \throws ThrowIfInvalidTruncatedSize() if the existing hash's size exceeds DigestSize() - //! \details Verify() performs a bitwise compare on the buffers using VerifyBufsEqual(), which is - //! a constant time comparison function. digestLength cannot exceed DigestSize(). - //! \details Verify() restarts the hash for the next message. - //! \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures - //! the output byte buffer is large enough for the digest. + /// \brief Verifies the hash of the current message + /// \param digest a pointer to the buffer of an \a existing hash + /// \return \p true if the existing hash matches the computed hash, \p false otherwise + /// \throws ThrowIfInvalidTruncatedSize() if the existing hash's size exceeds DigestSize() + /// \details Verify() performs a bitwise compare on the buffers using VerifyBufsEqual(), which is + /// a constant time comparison function. digestLength cannot exceed DigestSize(). + /// \details Verify() restarts the hash for the next message. + /// \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures + /// the output byte buffer is large enough for the digest. virtual bool Verify(const byte *digest) {return TruncatedVerify(digest, DigestSize());} - //! \brief Updates the hash with additional input and verifies the hash of the current message - //! \param digest a pointer to the buffer of an \a existing hash - //! \param input the additional input as a buffer - //! \param length the size of the buffer, in bytes - //! \return \p true if the existing hash matches the computed hash, \p false otherwise - //! \throws ThrowIfInvalidTruncatedSize() if the existing hash's size exceeds DigestSize() - //! \details Use this if your input is in one piece and you don't want to call Update() - //! and Verify() separately - //! \details VerifyDigest() performs a bitwise compare on the buffers using VerifyBufsEqual(), - //! which is a constant time comparison function. digestLength cannot exceed DigestSize(). - //! \details VerifyDigest() restarts the hash for the next message. - //! \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures - //! the output byte buffer is large enough for the digest. + /// \brief Updates the hash with additional input and verifies the hash of the current message + /// \param digest a pointer to the buffer of an \a existing hash + /// \param input the additional input as a buffer + /// \param length the size of the buffer, in bytes + /// \return \p true if the existing hash matches the computed hash, \p false otherwise + /// \throws ThrowIfInvalidTruncatedSize() if the existing hash's size exceeds DigestSize() + /// \details Use this if your input is in one piece and you don't want to call Update() + /// and Verify() separately + /// \details VerifyDigest() performs a bitwise compare on the buffers using VerifyBufsEqual(), + /// which is a constant time comparison function. digestLength cannot exceed DigestSize(). + /// \details VerifyDigest() restarts the hash for the next message. + /// \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures + /// the output byte buffer is large enough for the digest. virtual bool VerifyDigest(const byte *digest, const byte *input, size_t length) {Update(input, length); return Verify(digest);} - //! \brief Computes the hash of the current message - //! \param digest a pointer to the buffer to receive the hash - //! \param digestSize the size of the truncated digest, in bytes - //! \details TruncatedFinal() call Final() and then copies digestSize bytes to digest. - //! The hash is restarted the hash for the next message. + /// \brief Computes the hash of the current message + /// \param digest a pointer to the buffer to receive the hash + /// \param digestSize the size of the truncated digest, in bytes + /// \details TruncatedFinal() call Final() and then copies digestSize bytes to digest. + /// The hash is restarted the hash for the next message. virtual void TruncatedFinal(byte *digest, size_t digestSize) =0; - //! \brief Updates the hash with additional input and computes the hash of the current message - //! \param digest a pointer to the buffer to receive the hash - //! \param digestSize the length of the truncated hash, in bytes - //! \param input the additional input as a buffer - //! \param length the size of the buffer, in bytes - //! \details Use this if your input is in one piece and you don't want to call Update() - //! and CalculateDigest() separately. - //! \details CalculateTruncatedDigest() restarts the hash for the next message. - //! \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures - //! the output byte buffer is large enough for the digest. + /// \brief Updates the hash with additional input and computes the hash of the current message + /// \param digest a pointer to the buffer to receive the hash + /// \param digestSize the length of the truncated hash, in bytes + /// \param input the additional input as a buffer + /// \param length the size of the buffer, in bytes + /// \details Use this if your input is in one piece and you don't want to call Update() + /// and CalculateDigest() separately. + /// \details CalculateTruncatedDigest() restarts the hash for the next message. + /// \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures + /// the output byte buffer is large enough for the digest. virtual void CalculateTruncatedDigest(byte *digest, size_t digestSize, const byte *input, size_t length) {Update(input, length); TruncatedFinal(digest, digestSize);} - //! \brief Verifies the hash of the current message - //! \param digest a pointer to the buffer of an \a existing hash - //! \param digestLength the size of the truncated hash, in bytes - //! \return \p true if the existing hash matches the computed hash, \p false otherwise - //! \throws ThrowIfInvalidTruncatedSize() if digestLength exceeds DigestSize() - //! \details TruncatedVerify() is a truncated version of Verify(). It can operate on a - //! buffer smaller than DigestSize(). However, digestLength cannot exceed DigestSize(). - //! \details Verify() performs a bitwise compare on the buffers using VerifyBufsEqual(), which is - //! a constant time comparison function. digestLength cannot exceed DigestSize(). - //! \details TruncatedVerify() restarts the hash for the next message. + /// \brief Verifies the hash of the current message + /// \param digest a pointer to the buffer of an \a existing hash + /// \param digestLength the size of the truncated hash, in bytes + /// \return \p true if the existing hash matches the computed hash, \p false otherwise + /// \throws ThrowIfInvalidTruncatedSize() if digestLength exceeds DigestSize() + /// \details TruncatedVerify() is a truncated version of Verify(). It can operate on a + /// buffer smaller than DigestSize(). However, digestLength cannot exceed DigestSize(). + /// \details Verify() performs a bitwise compare on the buffers using VerifyBufsEqual(), which is + /// a constant time comparison function. digestLength cannot exceed DigestSize(). + /// \details TruncatedVerify() restarts the hash for the next message. virtual bool TruncatedVerify(const byte *digest, size_t digestLength); - //! \brief Updates the hash with additional input and verifies the hash of the current message - //! \param digest a pointer to the buffer of an \a existing hash - //! \param digestLength the size of the truncated hash, in bytes - //! \param input the additional input as a buffer - //! \param length the size of the buffer, in bytes - //! \return \p true if the existing hash matches the computed hash, \p false otherwise - //! \throws ThrowIfInvalidTruncatedSize() if digestLength exceeds DigestSize() - //! \details Use this if your input is in one piece and you don't want to call Update() - //! and TruncatedVerify() separately. - //! \details VerifyTruncatedDigest() is a truncated version of VerifyDigest(). It can operate - //! on a buffer smaller than DigestSize(). However, digestLength cannot exceed DigestSize(). - //! \details VerifyTruncatedDigest() restarts the hash for the next message. - //! \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures - //! the output byte buffer is large enough for the digest. + /// \brief Updates the hash with additional input and verifies the hash of the current message + /// \param digest a pointer to the buffer of an \a existing hash + /// \param digestLength the size of the truncated hash, in bytes + /// \param input the additional input as a buffer + /// \param length the size of the buffer, in bytes + /// \return \p true if the existing hash matches the computed hash, \p false otherwise + /// \throws ThrowIfInvalidTruncatedSize() if digestLength exceeds DigestSize() + /// \details Use this if your input is in one piece and you don't want to call Update() + /// and TruncatedVerify() separately. + /// \details VerifyTruncatedDigest() is a truncated version of VerifyDigest(). It can operate + /// on a buffer smaller than DigestSize(). However, digestLength cannot exceed DigestSize(). + /// \details VerifyTruncatedDigest() restarts the hash for the next message. + /// \pre COUNTOF(digest) == DigestSize() or COUNTOF(digest) == HASH::DIGESTSIZE ensures + /// the output byte buffer is large enough for the digest. virtual bool VerifyTruncatedDigest(const byte *digest, size_t digestLength, const byte *input, size_t length) {Update(input, length); return TruncatedVerify(digest, digestLength);} protected: - //! \brief Validates a truncated digest size - //! \param size the requested digest size - //! \throws InvalidArgument if the algorithm's digest size cannot be truncated to the requested size - //! \details Throws an exception when the truncated digest size is greater than DigestSize() + /// \brief Validates a truncated digest size + /// \param size the requested digest size + /// \throws InvalidArgument if the algorithm's digest size cannot be truncated to the requested size + /// \details Throws an exception when the truncated digest size is greater than DigestSize() void ThrowIfInvalidTruncatedSize(size_t size) const; }; -//! \brief Interface for one direction (encryption or decryption) of a block cipher -//! \details These objects usually should not be used directly. See BlockTransformation for more details. +/// \brief Interface for one direction (encryption or decryption) of a block cipher +/// \details These objects usually should not be used directly. See BlockTransformation for more details. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE BlockCipher : public SimpleKeyingInterface, public BlockTransformation { protected: const Algorithm & GetAlgorithm() const {return *this;} }; -//! \brief Interface for one direction (encryption or decryption) of a stream cipher or cipher mode -//! \details These objects usually should not be used directly. See StreamTransformation for more details. +/// \brief Interface for one direction (encryption or decryption) of a stream cipher or cipher mode +/// \details These objects usually should not be used directly. See StreamTransformation for more details. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE SymmetricCipher : public SimpleKeyingInterface, public StreamTransformation { protected: const Algorithm & GetAlgorithm() const {return *this;} }; -//! \brief Interface for message authentication codes -//! \details These objects usually should not be used directly. See HashTransformation for more details. +/// \brief Interface for message authentication codes +/// \details These objects usually should not be used directly. See HashTransformation for more details. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE MessageAuthenticationCode : public SimpleKeyingInterface, public HashTransformation { protected: const Algorithm & GetAlgorithm() const {return *this;} }; -//! \class AuthenticatedSymmetricCipher -//! \brief Interface for authenticated encryption modes of operation -//! \details AuthenticatedSymmetricCipher() provides the interface for one direction -//! (encryption or decryption) of a stream cipher or block cipher mode with authentication. The -//! StreamTransformation() part of this interface is used to encrypt or decrypt the data. The -//! MessageAuthenticationCode() part of the interface is used to input additional authenticated -//! data (AAD), which is MAC'ed but not encrypted. The MessageAuthenticationCode() part is also -//! used to generate and verify the MAC. -//! \details Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM -//! and OCB mode. All modes implement AuthenticatedSymmetricCipher() and the motivation for -//! the API, like calling AAD a "header", can be found in Bellare, Rogaway and -//! Wagner's The EAX Mode of -//! Operation. The EAX paper suggested a basic API to help standardize AEAD schemes in -//! software and promote adoption of the modes. -//! \sa Authenticated -//! Encryption on the Crypto++ wiki. -//! \since Crypto++ 5.6.0 +/// \class AuthenticatedSymmetricCipher +/// \brief Interface for authenticated encryption modes of operation +/// \details AuthenticatedSymmetricCipher() provides the interface for one direction +/// (encryption or decryption) of a stream cipher or block cipher mode with authentication. The +/// StreamTransformation() part of this interface is used to encrypt or decrypt the data. The +/// MessageAuthenticationCode() part of the interface is used to input additional authenticated +/// data (AAD), which is MAC'ed but not encrypted. The MessageAuthenticationCode() part is also +/// used to generate and verify the MAC. +/// \details Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM +/// and OCB mode. All modes implement AuthenticatedSymmetricCipher() and the motivation for +/// the API, like calling AAD a "header", can be found in Bellare, Rogaway and +/// Wagner's The EAX Mode of +/// Operation. The EAX paper suggested a basic API to help standardize AEAD schemes in +/// software and promote adoption of the modes. +/// \sa Authenticated +/// Encryption on the Crypto++ wiki. +/// \since Crypto++ 5.6.0 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AuthenticatedSymmetricCipher : public MessageAuthenticationCode, public StreamTransformation { public: virtual ~AuthenticatedSymmetricCipher() {} - //! \brief Exception thrown when the object is in the wrong state for the operation - //! \details this indicates that a member function was called in the wrong state, for example trying to encrypt - //! a message before having set the key or IV + /// \brief Exception thrown when the object is in the wrong state for the operation + /// \details this indicates that a member function was called in the wrong state, for example trying to encrypt + /// a message before having set the key or IV class BadState : public Exception { public: @@ -1283,40 +1283,40 @@ public: explicit BadState(const std::string &name, const char *function, const char *state) : Exception(OTHER_ERROR, name + ": " + function + " was called before " + state) {} }; - //! \brief Provides the maximum length of AAD that can be input - //! \return the maximum length of AAD that can be input before the encrypted data + /// \brief Provides the maximum length of AAD that can be input + /// \return the maximum length of AAD that can be input before the encrypted data virtual lword MaxHeaderLength() const =0; - //! \brief Provides the maximum length of encrypted data - //! \return the maximum length of encrypted data + /// \brief Provides the maximum length of encrypted data + /// \return the maximum length of encrypted data virtual lword MaxMessageLength() const =0; - //! \brief Provides the the maximum length of AAD - //! \return the maximum length of AAD that can be input after the encrypted data + /// \brief Provides the the maximum length of AAD + /// \return the maximum length of AAD that can be input after the encrypted data virtual lword MaxFooterLength() const {return 0;} - //! \brief Determines if data lengths must be specified prior to inputting data - //! \return true if the data lengths are required before inputting data, false otherwise - //! \details if this function returns true, SpecifyDataLengths() must be called before attempting to input data. - //! This is the case for some schemes, such as CCM. - //! \sa SpecifyDataLengths() + /// \brief Determines if data lengths must be specified prior to inputting data + /// \return true if the data lengths are required before inputting data, false otherwise + /// \details if this function returns true, SpecifyDataLengths() must be called before attempting to input data. + /// This is the case for some schemes, such as CCM. + /// \sa SpecifyDataLengths() virtual bool NeedsPrespecifiedDataLengths() const {return false;} - //! \brief Prespecifies the data lengths - //! \details this function only needs to be called if NeedsPrespecifiedDataLengths() returns true - //! \sa NeedsPrespecifiedDataLengths() + /// \brief Prespecifies the data lengths + /// \details this function only needs to be called if NeedsPrespecifiedDataLengths() returns true + /// \sa NeedsPrespecifiedDataLengths() void SpecifyDataLengths(lword headerLength, lword messageLength, lword footerLength=0); - //! \brief Encrypts and calculates a MAC in one call - //! \details EncryptAndAuthenticate() encrypts and generates the MAC in one call. The function will truncate MAC if - //! macSize < TagSize(). + /// \brief Encrypts and calculates a MAC in one call + /// \details EncryptAndAuthenticate() encrypts and generates the MAC in one call. The function will truncate MAC if + /// macSize < TagSize(). virtual void EncryptAndAuthenticate(byte *ciphertext, byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *header, size_t headerLength, const byte *message, size_t messageLength); - //! \brief Decrypts and verifies a MAC in one call - //! \return true if the MAC is valid and the decoding succeeded, false otherwise - //! \details DecryptAndVerify() decrypts and verifies the MAC in one call. The function returns true iff MAC is valid. - //! DecryptAndVerify() will assume MAC is truncated if macLength < TagSize(). + /// \brief Decrypts and verifies a MAC in one call + /// \return true if the MAC is valid and the decoding succeeded, false otherwise + /// \details DecryptAndVerify() decrypts and verifies the MAC in one call. The function returns true iff MAC is valid. + /// DecryptAndVerify() will assume MAC is truncated if macLength < TagSize(). virtual bool DecryptAndVerify(byte *message, const byte *mac, size_t macLength, const byte *iv, int ivLength, const byte *header, size_t headerLength, const byte *ciphertext, size_t ciphertextLength); - //! \brief Provides the name of this algorithm - //! \return the standard algorithm name - //! \details The standard algorithm name can be a name like \a AES or \a AES/GCM. Some algorithms - //! do not have standard names yet. For example, there is no standard algorithm name for - //! Shoup's ECIES. + /// \brief Provides the name of this algorithm + /// \return the standard algorithm name + /// \details The standard algorithm name can be a name like \a AES or \a AES/GCM. Some algorithms + /// do not have standard names yet. For example, there is no standard algorithm name for + /// Shoup's ECIES. virtual std::string AlgorithmName() const =0; protected: @@ -1326,86 +1326,86 @@ protected: {CRYPTOPP_UNUSED(headerLength); CRYPTOPP_UNUSED(messageLength); CRYPTOPP_UNUSED(footerLength);} }; -//! \class RandomNumberGenerator -//! \brief Interface for random number generators -//! \details The library provides a number of random number generators, from software based to hardware based generators. -//! \details All generated values are uniformly distributed over the range specified. +/// \class RandomNumberGenerator +/// \brief Interface for random number generators +/// \details The library provides a number of random number generators, from software based to hardware based generators. +/// \details All generated values are uniformly distributed over the range specified. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE RandomNumberGenerator : public Algorithm { public: virtual ~RandomNumberGenerator() {} - //! \brief Update RNG state with additional unpredictable values - //! \param input the entropy to add to the generator - //! \param length the size of the input buffer - //! \throws NotImplemented - //! \details A generator may or may not accept additional entropy. Call CanIncorporateEntropy() to test for the - //! ability to use additional entropy. - //! \details If a derived class does not override IncorporateEntropy(), then the base class throws - //! NotImplemented. + /// \brief Update RNG state with additional unpredictable values + /// \param input the entropy to add to the generator + /// \param length the size of the input buffer + /// \throws NotImplemented + /// \details A generator may or may not accept additional entropy. Call CanIncorporateEntropy() to test for the + /// ability to use additional entropy. + /// \details If a derived class does not override IncorporateEntropy(), then the base class throws + /// NotImplemented. virtual void IncorporateEntropy(const byte *input, size_t length) { CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(length); throw NotImplemented("RandomNumberGenerator: IncorporateEntropy not implemented"); } - //! \brief Determines if a generator can accept additional entropy - //! \return true if IncorporateEntropy() is implemented + /// \brief Determines if a generator can accept additional entropy + /// \return true if IncorporateEntropy() is implemented virtual bool CanIncorporateEntropy() const {return false;} - //! \brief Generate new random byte and return it - //! \return a random 8-bit byte - //! \details Default implementation calls GenerateBlock() with one byte. - //! \details All generated values are uniformly distributed over the range specified within the - //! the constraints of a particular generator. + /// \brief Generate new random byte and return it + /// \return a random 8-bit byte + /// \details Default implementation calls GenerateBlock() with one byte. + /// \details All generated values are uniformly distributed over the range specified within the + /// the constraints of a particular generator. virtual byte GenerateByte(); - //! \brief Generate new random bit and return it - //! \return a random bit - //! \details The default implementation calls GenerateByte() and return its lowest bit. - //! \details All generated values are uniformly distributed over the range specified within the - //! the constraints of a particular generator. + /// \brief Generate new random bit and return it + /// \return a random bit + /// \details The default implementation calls GenerateByte() and return its lowest bit. + /// \details All generated values are uniformly distributed over the range specified within the + /// the constraints of a particular generator. virtual unsigned int GenerateBit(); - //! \brief Generate a random 32 bit word in the range min to max, inclusive - //! \param min the lower bound of the range - //! \param max the upper bound of the range - //! \return a random 32-bit word - //! \details The default implementation calls Crop() on the difference between max and - //! min, and then returns the result added to min. - //! \details All generated values are uniformly distributed over the range specified within the - //! the constraints of a particular generator. + /// \brief Generate a random 32 bit word in the range min to max, inclusive + /// \param min the lower bound of the range + /// \param max the upper bound of the range + /// \return a random 32-bit word + /// \details The default implementation calls Crop() on the difference between max and + /// min, and then returns the result added to min. + /// \details All generated values are uniformly distributed over the range specified within the + /// the constraints of a particular generator. virtual word32 GenerateWord32(word32 min=0, word32 max=0xffffffffUL); - //! \brief Generate random array of bytes - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes - //! \details All generated values are uniformly distributed over the range specified within the - //! the constraints of a particular generator. - //! \note A derived generator \a must override either GenerateBlock() or - //! GenerateIntoBufferedTransformation(). They can override both, or have one call the other. + /// \brief Generate random array of bytes + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes + /// \details All generated values are uniformly distributed over the range specified within the + /// the constraints of a particular generator. + /// \note A derived generator \a must override either GenerateBlock() or + /// GenerateIntoBufferedTransformation(). They can override both, or have one call the other. virtual void GenerateBlock(byte *output, size_t size); - //! \brief Generate random bytes into a BufferedTransformation - //! \param target the BufferedTransformation object which receives the bytes - //! \param channel the channel on which the bytes should be pumped - //! \param length the number of bytes to generate - //! \details The default implementation calls GenerateBlock() and pumps the result into - //! the DEFAULT_CHANNEL of the target. - //! \details All generated values are uniformly distributed over the range specified within the - //! the constraints of a particular generator. - //! \note A derived generator \a must override either GenerateBlock() or - //! GenerateIntoBufferedTransformation(). They can override both, or have one call the other. + /// \brief Generate random bytes into a BufferedTransformation + /// \param target the BufferedTransformation object which receives the bytes + /// \param channel the channel on which the bytes should be pumped + /// \param length the number of bytes to generate + /// \details The default implementation calls GenerateBlock() and pumps the result into + /// the DEFAULT_CHANNEL of the target. + /// \details All generated values are uniformly distributed over the range specified within the + /// the constraints of a particular generator. + /// \note A derived generator \a must override either GenerateBlock() or + /// GenerateIntoBufferedTransformation(). They can override both, or have one call the other. virtual void GenerateIntoBufferedTransformation(BufferedTransformation &target, const std::string &channel, lword length); - //! \brief Generate and discard n bytes - //! \param n the number of bytes to generate and discard + /// \brief Generate and discard n bytes + /// \param n the number of bytes to generate and discard virtual void DiscardBytes(size_t n); - //! \brief Randomly shuffle the specified array - //! \param begin an iterator to the first element in the array - //! \param end an iterator beyond the last element in the array - //! \details The resulting permutation is uniformly distributed. + /// \brief Randomly shuffle the specified array + /// \param begin an iterator to the first element in the array + /// \param end an iterator beyond the last element in the array + /// \details The resulting permutation is uniformly distributed. template void Shuffle(IT begin, IT end) { // TODO: What happens if there are more than 2^32 elements? @@ -1414,743 +1414,743 @@ public: } }; -//! \brief Random Number Generator that does not produce random numbers -//! \return reference that can be passed to functions that require a RandomNumberGenerator -//! \details NullRNG() returns a reference that can be passed to functions that require a -//! RandomNumberGenerator but don't actually use it. The NullRNG() throws NotImplemented -//! when a generation function is called. -//! \sa ClassNullRNG, PK_SignatureScheme::IsProbabilistic() +/// \brief Random Number Generator that does not produce random numbers +/// \return reference that can be passed to functions that require a RandomNumberGenerator +/// \details NullRNG() returns a reference that can be passed to functions that require a +/// RandomNumberGenerator but don't actually use it. The NullRNG() throws NotImplemented +/// when a generation function is called. +/// \sa ClassNullRNG, PK_SignatureScheme::IsProbabilistic() CRYPTOPP_DLL RandomNumberGenerator & CRYPTOPP_API NullRNG(); -//! \class WaitObjectContainer +/// \class WaitObjectContainer class WaitObjectContainer; -//! \class CallStack +/// \class CallStack class CallStack; -//! \brief Interface for objects that can be waited on. +/// \brief Interface for objects that can be waited on. class CRYPTOPP_NO_VTABLE Waitable { public: virtual ~Waitable() {} - //! \brief Maximum number of wait objects that this object can return - //! \return the maximum number of wait objects + /// \brief Maximum number of wait objects that this object can return + /// \return the maximum number of wait objects virtual unsigned int GetMaxWaitObjectCount() const =0; - //! \brief Retrieves waitable objects - //! \param container the wait container to receive the references to the objects. - //! \param callStack CallStack() object used to select waitable objects - //! \details GetWaitObjects() is usually called in one of two ways. First, it can - //! be called like something.GetWaitObjects(c, CallStack("my func after X", 0));. - //! Second, if in an outer GetWaitObjects() method that itself takes a callStack - //! parameter, it can be called like - //! innerThing.GetWaitObjects(c, CallStack("MyClass::GetWaitObjects at X", &callStack));. + /// \brief Retrieves waitable objects + /// \param container the wait container to receive the references to the objects. + /// \param callStack CallStack() object used to select waitable objects + /// \details GetWaitObjects() is usually called in one of two ways. First, it can + /// be called like something.GetWaitObjects(c, CallStack("my func after X", 0));. + /// Second, if in an outer GetWaitObjects() method that itself takes a callStack + /// parameter, it can be called like + /// innerThing.GetWaitObjects(c, CallStack("MyClass::GetWaitObjects at X", &callStack));. virtual void GetWaitObjects(WaitObjectContainer &container, CallStack const& callStack) =0; - //! \brief Wait on this object - //! \return true if the wait succeeded, false otherwise - //! \details Wait() is the same as creating an empty container, calling GetWaitObjects(), and then calling - //! Wait() on the container. + /// \brief Wait on this object + /// \return true if the wait succeeded, false otherwise + /// \details Wait() is the same as creating an empty container, calling GetWaitObjects(), and then calling + /// Wait() on the container. bool Wait(unsigned long milliseconds, CallStack const& callStack); }; -//! \brief Interface for buffered transformations -//! \details BufferedTransformation is a generalization of BlockTransformation, -//! StreamTransformation and HashTransformation. -//! \details A buffered transformation is an object that takes a stream of bytes as input (this may -//! be done in stages), does some computation on them, and then places the result into an internal -//! buffer for later retrieval. Any partial result already in the output buffer is not modified -//! by further input. -//! \details If a method takes a "blocking" parameter, and you pass false for it, then the method -//! will return before all input has been processed if the input cannot be processed without waiting -//! (for network buffers to become available, for example). In this case the method will return true -//! or a non-zero integer value. When this happens you must continue to call the method with the same -//! parameters until it returns false or zero, before calling any other method on it or attached -//! /p BufferedTransformation. The integer return value in this case is approximately -//! the number of bytes left to be processed, and can be used to implement a progress bar. -//! \details For functions that take a "propagation" parameter, propagation != 0 means pass on -//! the signal to attached BufferedTransformation objects, with propagation decremented at each -//! step until it reaches 0. -1 means unlimited propagation. -//! \details \a All of the retrieval functions, like Get() and GetWord32(), return the actual -//! number of bytes retrieved, which is the lesser of the request number and MaxRetrievable(). -//! \details \a Most of the input functions, like Put() and PutWord32(), return the number of -//! bytes remaining to be processed. A 0 value means all bytes were processed, and a non-0 value -//! means bytes remain to be processed. -//! \nosubgrouping +/// \brief Interface for buffered transformations +/// \details BufferedTransformation is a generalization of BlockTransformation, +/// StreamTransformation and HashTransformation. +/// \details A buffered transformation is an object that takes a stream of bytes as input (this may +/// be done in stages), does some computation on them, and then places the result into an internal +/// buffer for later retrieval. Any partial result already in the output buffer is not modified +/// by further input. +/// \details If a method takes a "blocking" parameter, and you pass false for it, then the method +/// will return before all input has been processed if the input cannot be processed without waiting +/// (for network buffers to become available, for example). In this case the method will return true +/// or a non-zero integer value. When this happens you must continue to call the method with the same +/// parameters until it returns false or zero, before calling any other method on it or attached +/// /p BufferedTransformation. The integer return value in this case is approximately +/// the number of bytes left to be processed, and can be used to implement a progress bar. +/// \details For functions that take a "propagation" parameter, propagation != 0 means pass on +/// the signal to attached BufferedTransformation objects, with propagation decremented at each +/// step until it reaches 0. -1 means unlimited propagation. +/// \details \a All of the retrieval functions, like Get() and GetWord32(), return the actual +/// number of bytes retrieved, which is the lesser of the request number and MaxRetrievable(). +/// \details \a Most of the input functions, like Put() and PutWord32(), return the number of +/// bytes remaining to be processed. A 0 value means all bytes were processed, and a non-0 value +/// means bytes remain to be processed. +/// \nosubgrouping class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE BufferedTransformation : public Algorithm, public Waitable { public: virtual ~BufferedTransformation() {} - //! \brief Construct a BufferedTransformation + /// \brief Construct a BufferedTransformation BufferedTransformation() : Algorithm(false) {} - //! \brief Provides a reference to this object - //! \return A reference to this object - //! \details Useful for passing a temporary object to a function that takes a non-const reference + /// \brief Provides a reference to this object + /// \return A reference to this object + /// \details Useful for passing a temporary object to a function that takes a non-const reference BufferedTransformation& Ref() {return *this;} - //! \name INPUT + /// \name INPUT //@{ - //! \brief Input a byte for processing - //! \param inByte the 8-bit byte (octet) to be processed. - //! \param blocking specifies whether the object should block when processing input. - //! \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all - //! bytes were processed. - //! \details Put(byte) calls Put(byte*, size_t). + /// \brief Input a byte for processing + /// \param inByte the 8-bit byte (octet) to be processed. + /// \param blocking specifies whether the object should block when processing input. + /// \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all + /// bytes were processed. + /// \details Put(byte) calls Put(byte*, size_t). size_t Put(byte inByte, bool blocking=true) {return Put(&inByte, 1, blocking);} - //! \brief Input a byte buffer for processing - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all - //! bytes were processed. - //! \details Internally, Put() calls Put2(). + /// \brief Input a byte buffer for processing + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all + /// bytes were processed. + /// \details Internally, Put() calls Put2(). size_t Put(const byte *inString, size_t length, bool blocking=true) {return Put2(inString, length, 0, blocking);} - //! Input a 16-bit word for processing. - //! \param value the 16-bit value to be processed - //! \param order the ByteOrder of the value to be processed. - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all - //! bytes were processed. + /// Input a 16-bit word for processing. + /// \param value the 16-bit value to be processed + /// \param order the ByteOrder of the value to be processed. + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all + /// bytes were processed. size_t PutWord16(word16 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true); - //! Input a 32-bit word for processing. - //! \param value the 32-bit value to be processed. - //! \param order the ByteOrder of the value to be processed. - //! \param blocking specifies whether the object should block when processing input. - //! \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all - //! bytes were processed. + /// Input a 32-bit word for processing. + /// \param value the 32-bit value to be processed. + /// \param order the ByteOrder of the value to be processed. + /// \param blocking specifies whether the object should block when processing input. + /// \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all + /// bytes were processed. size_t PutWord32(word32 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true); - //! \brief Request space which can be written into by the caller - //! \param size the requested size of the buffer - //! \return byte pointer to the space to input data - //! \details The purpose of this method is to help avoid extra memory allocations. - //! \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, - //! size is the requested size of the buffer. When the call returns, size is the size of - //! the array returned to the caller. - //! \details The base class implementation sets size to 0 and returns NULL. - //! \note Some objects, like ArraySink, cannot create a space because its fixed. In the case of - //! an ArraySink, the pointer to the array is returned and the size is remaining size. + /// \brief Request space which can be written into by the caller + /// \param size the requested size of the buffer + /// \return byte pointer to the space to input data + /// \details The purpose of this method is to help avoid extra memory allocations. + /// \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, + /// size is the requested size of the buffer. When the call returns, size is the size of + /// the array returned to the caller. + /// \details The base class implementation sets size to 0 and returns NULL. + /// \note Some objects, like ArraySink, cannot create a space because its fixed. In the case of + /// an ArraySink, the pointer to the array is returned and the size is remaining size. virtual byte * CreatePutSpace(size_t &size) {size=0; return NULLPTR;} - //! \brief Determines whether input can be modified by the callee - //! \return true if input can be modified, false otherwise - //! \details The base class implementation returns false. + /// \brief Determines whether input can be modified by the callee + /// \return true if input can be modified, false otherwise + /// \details The base class implementation returns false. virtual bool CanModifyInput() const {return false;} - //! \brief Input multiple bytes that may be modified by callee. - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all - //! bytes were processed. + /// \brief Input multiple bytes that may be modified by callee. + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all + /// bytes were processed. size_t PutModifiable(byte *inString, size_t length, bool blocking=true) {return PutModifiable2(inString, length, 0, blocking);} - //! \brief Signals the end of messages to the object - //! \param propagation the number of attached transformations the MessageEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. + /// \brief Signals the end of messages to the object + /// \param propagation the number of attached transformations the MessageEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. bool MessageEnd(int propagation=-1, bool blocking=true) {return !!Put2(NULLPTR, 0, propagation < 0 ? -1 : propagation+1, blocking);} - //! \brief Input multiple bytes for processing and signal the end of a message - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param propagation the number of attached transformations the MessageEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all - //! bytes were processed. - //! \details Internally, PutMessageEnd() calls Put2() with a modified propagation to - //! ensure all attached transformations finish processing the message. - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. + /// \brief Input multiple bytes for processing and signal the end of a message + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param propagation the number of attached transformations the MessageEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all + /// bytes were processed. + /// \details Internally, PutMessageEnd() calls Put2() with a modified propagation to + /// ensure all attached transformations finish processing the message. + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. size_t PutMessageEnd(const byte *inString, size_t length, int propagation=-1, bool blocking=true) {return Put2(inString, length, propagation < 0 ? -1 : propagation+1, blocking);} - //! \brief Input multiple bytes for processing - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all - //! bytes were processed. - //! \details Derived classes must implement Put2(). + /// \brief Input multiple bytes for processing + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all + /// bytes were processed. + /// \details Derived classes must implement Put2(). virtual size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking) =0; - //! \brief Input multiple bytes that may be modified by callee. - //! \param inString the byte buffer to process. - //! \param length the size of the string, in bytes. - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one. - //! \param blocking specifies whether the object should block when processing input. - //! \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all - //! bytes were processed. - //! \details Internally, PutModifiable2() calls Put2(). + /// \brief Input multiple bytes that may be modified by callee. + /// \param inString the byte buffer to process. + /// \param length the size of the string, in bytes. + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one. + /// \param blocking specifies whether the object should block when processing input. + /// \return the number of bytes that remain in the block (i.e., bytes not processed). 0 indicates all + /// bytes were processed. + /// \details Internally, PutModifiable2() calls Put2(). virtual size_t PutModifiable2(byte *inString, size_t length, int messageEnd, bool blocking) {return Put2(inString, length, messageEnd, blocking);} - //! \class BlockingInputOnly - //! \brief Exception thrown by objects that have \a not implemented nonblocking input processing - //! \details BlockingInputOnly inherits from NotImplemented + /// \class BlockingInputOnly + /// \brief Exception thrown by objects that have \a not implemented nonblocking input processing + /// \details BlockingInputOnly inherits from NotImplemented struct BlockingInputOnly : public NotImplemented {BlockingInputOnly(const std::string &s) : NotImplemented(s + ": Nonblocking input is not implemented by this object.") {}}; //@} - //! \name WAITING + /// \name WAITING //@{ - //! \brief Retrieves the maximum number of waitable objects + /// \brief Retrieves the maximum number of waitable objects unsigned int GetMaxWaitObjectCount() const; - //! \brief Retrieves waitable objects - //! \param container the wait container to receive the references to the objects - //! \param callStack CallStack() object used to select waitable objects - //! \details GetWaitObjects is usually called in one of two ways. First, it can - //! be called like something.GetWaitObjects(c, CallStack("my func after X", 0));. - //! Second, if in an outer GetWaitObjects() method that itself takes a callStack - //! parameter, it can be called like - //! innerThing.GetWaitObjects(c, CallStack("MyClass::GetWaitObjects at X", &callStack));. + /// \brief Retrieves waitable objects + /// \param container the wait container to receive the references to the objects + /// \param callStack CallStack() object used to select waitable objects + /// \details GetWaitObjects is usually called in one of two ways. First, it can + /// be called like something.GetWaitObjects(c, CallStack("my func after X", 0));. + /// Second, if in an outer GetWaitObjects() method that itself takes a callStack + /// parameter, it can be called like + /// innerThing.GetWaitObjects(c, CallStack("MyClass::GetWaitObjects at X", &callStack));. void GetWaitObjects(WaitObjectContainer &container, CallStack const& callStack); //@} // WAITING - //! \name SIGNALS + /// \name SIGNALS //@{ - //! \brief Initialize or reinitialize this object, without signal propagation - //! \param parameters a set of NameValuePairs to initialize this object - //! \throws NotImplemented - //! \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable - //! number of arbitrarily typed arguments. The function avoids the need for multiple constructors providing - //! all possible combintations of configurable parameters. - //! \details IsolatedInitialize() does not call Initialize() on attached transformations. If initialization - //! should be propagated, then use the Initialize() function. - //! \details If a derived class does not override IsolatedInitialize(), then the base class throws - //! NotImplemented. + /// \brief Initialize or reinitialize this object, without signal propagation + /// \param parameters a set of NameValuePairs to initialize this object + /// \throws NotImplemented + /// \details IsolatedInitialize() is used to initialize or reinitialize an object using a variable + /// number of arbitrarily typed arguments. The function avoids the need for multiple constructors providing + /// all possible combintations of configurable parameters. + /// \details IsolatedInitialize() does not call Initialize() on attached transformations. If initialization + /// should be propagated, then use the Initialize() function. + /// \details If a derived class does not override IsolatedInitialize(), then the base class throws + /// NotImplemented. virtual void IsolatedInitialize(const NameValuePairs ¶meters) { CRYPTOPP_UNUSED(parameters); throw NotImplemented("BufferedTransformation: this object can't be reinitialized"); } - //! \brief Flushes data buffered by this object, without signal propagation - //! \param hardFlush indicates whether all data should be flushed - //! \param blocking specifies whether the object should block when processing input - //! \note hardFlush must be used with care + /// \brief Flushes data buffered by this object, without signal propagation + /// \param hardFlush indicates whether all data should be flushed + /// \param blocking specifies whether the object should block when processing input + /// \note hardFlush must be used with care virtual bool IsolatedFlush(bool hardFlush, bool blocking) =0; - //! \brief Marks the end of a series of messages, without signal propagation - //! \param blocking specifies whether the object should block when completing the processing on - //! the current series of messages + /// \brief Marks the end of a series of messages, without signal propagation + /// \param blocking specifies whether the object should block when completing the processing on + /// the current series of messages virtual bool IsolatedMessageSeriesEnd(bool blocking) {CRYPTOPP_UNUSED(blocking); return false;} - //! \brief Initialize or reinitialize this object, with signal propagation - //! \param parameters a set of NameValuePairs to initialize or reinitialize this object - //! \param propagation the number of attached transformations the Initialize() signal should be passed - //! \details Initialize() is used to initialize or reinitialize an object using a variable number of - //! arbitrarily typed arguments. The function avoids the need for multiple constructors providing - //! all possible combintations of configurable parameters. - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. + /// \brief Initialize or reinitialize this object, with signal propagation + /// \param parameters a set of NameValuePairs to initialize or reinitialize this object + /// \param propagation the number of attached transformations the Initialize() signal should be passed + /// \details Initialize() is used to initialize or reinitialize an object using a variable number of + /// arbitrarily typed arguments. The function avoids the need for multiple constructors providing + /// all possible combintations of configurable parameters. + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. virtual void Initialize(const NameValuePairs ¶meters=g_nullNameValuePairs, int propagation=-1); - //! \brief Flush buffered input and/or output, with signal propagation - //! \param hardFlush is used to indicate whether all data should be flushed - //! \param propagation the number of attached transformations the Flush() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. - //! \note Hard flushes must be used with care. It means try to process and output everything, even if - //! there may not be enough data to complete the action. For example, hard flushing a HexDecoder - //! would cause an error if you do it after inputing an odd number of hex encoded characters. - //! \note For some types of filters, like ZlibDecompressor, hard flushes can only - //! be done at "synchronization points". These synchronization points are positions in the data - //! stream that are created by hard flushes on the corresponding reverse filters, in this - //! example ZlibCompressor. This is useful when zlib compressed data is moved across a - //! network in packets and compression state is preserved across packets, as in the SSH2 protocol. + /// \brief Flush buffered input and/or output, with signal propagation + /// \param hardFlush is used to indicate whether all data should be flushed + /// \param propagation the number of attached transformations the Flush() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. + /// \note Hard flushes must be used with care. It means try to process and output everything, even if + /// there may not be enough data to complete the action. For example, hard flushing a HexDecoder + /// would cause an error if you do it after inputing an odd number of hex encoded characters. + /// \note For some types of filters, like ZlibDecompressor, hard flushes can only + /// be done at "synchronization points". These synchronization points are positions in the data + /// stream that are created by hard flushes on the corresponding reverse filters, in this + /// example ZlibCompressor. This is useful when zlib compressed data is moved across a + /// network in packets and compression state is preserved across packets, as in the SSH2 protocol. virtual bool Flush(bool hardFlush, int propagation=-1, bool blocking=true); - //! \brief Marks the end of a series of messages, with signal propagation - //! \param propagation the number of attached transformations the MessageSeriesEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \details Each object that receives the signal will perform its processing, decrement - //! propagation, and then pass the signal on to attached transformations if the value is not 0. - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. - //! \note There should be a MessageEnd() immediately before MessageSeriesEnd(). + /// \brief Marks the end of a series of messages, with signal propagation + /// \param propagation the number of attached transformations the MessageSeriesEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \details Each object that receives the signal will perform its processing, decrement + /// propagation, and then pass the signal on to attached transformations if the value is not 0. + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. + /// \note There should be a MessageEnd() immediately before MessageSeriesEnd(). virtual bool MessageSeriesEnd(int propagation=-1, bool blocking=true); - //! \brief Set propagation of automatically generated and transferred signals - //! \param propagation then new value - //! \details Setting propagation to 0 means do not automatically generate signals. Setting - //! propagation to -1 means unlimited propagation. + /// \brief Set propagation of automatically generated and transferred signals + /// \param propagation then new value + /// \details Setting propagation to 0 means do not automatically generate signals. Setting + /// propagation to -1 means unlimited propagation. virtual void SetAutoSignalPropagation(int propagation) {CRYPTOPP_UNUSED(propagation);} - //! \brief Retrieve automatic signal propagation value - //! \return the number of attached transformations the signal is propagated to. 0 indicates - //! the signal is only witnessed by this object + /// \brief Retrieve automatic signal propagation value + /// \return the number of attached transformations the signal is propagated to. 0 indicates + /// the signal is only witnessed by this object virtual int GetAutoSignalPropagation() const {return 0;} public: - //! \name RETRIEVAL OF ONE MESSAGE + /// \name RETRIEVAL OF ONE MESSAGE //@{ - //! \brief Provides the number of bytes ready for retrieval - //! \return the number of bytes ready for retrieval - //! \details All retrieval functions return the actual number of bytes retrieved, which is - //! the lesser of the request number and MaxRetrievable() + /// \brief Provides the number of bytes ready for retrieval + /// \return the number of bytes ready for retrieval + /// \details All retrieval functions return the actual number of bytes retrieved, which is + /// the lesser of the request number and MaxRetrievable() virtual lword MaxRetrievable() const; - //! \brief Determines whether bytes are ready for retrieval - //! \returns true if bytes are available for retrieval, false otherwise + /// \brief Determines whether bytes are ready for retrieval + /// \returns true if bytes are available for retrieval, false otherwise virtual bool AnyRetrievable() const; - //! \brief Retrieve a 8-bit byte - //! \param outByte the 8-bit value to be retrieved - //! \return the number of bytes consumed during the call. - //! \details Use the return value of Get to detect short reads. + /// \brief Retrieve a 8-bit byte + /// \param outByte the 8-bit value to be retrieved + /// \return the number of bytes consumed during the call. + /// \details Use the return value of Get to detect short reads. virtual size_t Get(byte &outByte); - //! \brief Retrieve a block of bytes - //! \param outString a block of bytes - //! \param getMax the number of bytes to Get - //! \return the number of bytes consumed during the call. - //! \details Use the return value of Get to detect short reads. + /// \brief Retrieve a block of bytes + /// \param outString a block of bytes + /// \param getMax the number of bytes to Get + /// \return the number of bytes consumed during the call. + /// \details Use the return value of Get to detect short reads. virtual size_t Get(byte *outString, size_t getMax); - //! \brief Peek a 8-bit byte - //! \param outByte the 8-bit value to be retrieved - //! \return the number of bytes read during the call. - //! \details Peek does not remove bytes from the object. Use the return value of - //! Get() to detect short reads. + /// \brief Peek a 8-bit byte + /// \param outByte the 8-bit value to be retrieved + /// \return the number of bytes read during the call. + /// \details Peek does not remove bytes from the object. Use the return value of + /// Get() to detect short reads. virtual size_t Peek(byte &outByte) const; - //! \brief Peek a block of bytes - //! \param outString a block of bytes - //! \param peekMax the number of bytes to Peek - //! \return the number of bytes read during the call. - //! \details Peek does not remove bytes from the object. Use the return value of - //! Get() to detect short reads. + /// \brief Peek a block of bytes + /// \param outString a block of bytes + /// \param peekMax the number of bytes to Peek + /// \return the number of bytes read during the call. + /// \details Peek does not remove bytes from the object. Use the return value of + /// Get() to detect short reads. virtual size_t Peek(byte *outString, size_t peekMax) const; - //! \brief Retrieve a 16-bit word - //! \param value the 16-bit value to be retrieved - //! \param order the ByteOrder of the value to be processed. - //! \return the number of bytes consumed during the call. - //! \details Use the return value of GetWord16() to detect short reads. + /// \brief Retrieve a 16-bit word + /// \param value the 16-bit value to be retrieved + /// \param order the ByteOrder of the value to be processed. + /// \return the number of bytes consumed during the call. + /// \details Use the return value of GetWord16() to detect short reads. size_t GetWord16(word16 &value, ByteOrder order=BIG_ENDIAN_ORDER); - //! \brief Retrieve a 32-bit word - //! \param value the 32-bit value to be retrieved - //! \param order the ByteOrder of the value to be processed. - //! \return the number of bytes consumed during the call. - //! \details Use the return value of GetWord16() to detect short reads. + /// \brief Retrieve a 32-bit word + /// \param value the 32-bit value to be retrieved + /// \param order the ByteOrder of the value to be processed. + /// \return the number of bytes consumed during the call. + /// \details Use the return value of GetWord16() to detect short reads. size_t GetWord32(word32 &value, ByteOrder order=BIG_ENDIAN_ORDER); - //! \brief Peek a 16-bit word - //! \param value the 16-bit value to be retrieved - //! \param order the ByteOrder of the value to be processed. - //! \return the number of bytes consumed during the call. - //! \details Peek does not consume bytes in the stream. Use the return value - //! of GetWord16() to detect short reads. + /// \brief Peek a 16-bit word + /// \param value the 16-bit value to be retrieved + /// \param order the ByteOrder of the value to be processed. + /// \return the number of bytes consumed during the call. + /// \details Peek does not consume bytes in the stream. Use the return value + /// of GetWord16() to detect short reads. size_t PeekWord16(word16 &value, ByteOrder order=BIG_ENDIAN_ORDER) const; - //! \brief Peek a 32-bit word - //! \param value the 32-bit value to be retrieved - //! \param order the ByteOrder of the value to be processed. - //! \return the number of bytes consumed during the call. - //! \details Peek does not consume bytes in the stream. Use the return value - //! of GetWord16() to detect short reads. + /// \brief Peek a 32-bit word + /// \param value the 32-bit value to be retrieved + /// \param order the ByteOrder of the value to be processed. + /// \return the number of bytes consumed during the call. + /// \details Peek does not consume bytes in the stream. Use the return value + /// of GetWord16() to detect short reads. size_t PeekWord32(word32 &value, ByteOrder order=BIG_ENDIAN_ORDER) const; - //! move transferMax bytes of the buffered output to target as input + /// move transferMax bytes of the buffered output to target as input - //! \brief Transfer bytes from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param transferMax the number of bytes to transfer - //! \param channel the channel on which the transfer should occur - //! \return the number of bytes transferred during the call. - //! \details TransferTo removes bytes from this object and moves them to the destination. - //! \details The function always returns transferMax. If an accurate count is needed, then use TransferTo2(). + /// \brief Transfer bytes from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param transferMax the number of bytes to transfer + /// \param channel the channel on which the transfer should occur + /// \return the number of bytes transferred during the call. + /// \details TransferTo removes bytes from this object and moves them to the destination. + /// \details The function always returns transferMax. If an accurate count is needed, then use TransferTo2(). lword TransferTo(BufferedTransformation &target, lword transferMax=LWORD_MAX, const std::string &channel=DEFAULT_CHANNEL) {TransferTo2(target, transferMax, channel); return transferMax;} - //! \brief Discard skipMax bytes from the output buffer - //! \param skipMax the number of bytes to discard - //! \details Skip() discards bytes from the output buffer, which is the AttachedTransformation(), if present. - //! The function always returns the parameter skipMax. - //! \details If you want to skip bytes from a Source, then perform the following. - //! 
-		//!     StringSource ss(str, false, new Redirector(TheBitBucket()));
-		//!     ss.Pump(10);    // Skip 10 bytes from Source
-		//!     ss.Detach(new FilterChain(...));
-		//!     ss.PumpAll();
-		//!
+ /// \brief Discard skipMax bytes from the output buffer + /// \param skipMax the number of bytes to discard + /// \details Skip() discards bytes from the output buffer, which is the AttachedTransformation(), if present. + /// The function always returns the parameter skipMax. + /// \details If you want to skip bytes from a Source, then perform the following. + /// 
+		///     StringSource ss(str, false, new Redirector(TheBitBucket()));
+		///     ss.Pump(10);    // Skip 10 bytes from Source
+		///     ss.Detach(new FilterChain(...));
+		///     ss.PumpAll();
+		///
virtual lword Skip(lword skipMax=LWORD_MAX); - //! copy copyMax bytes of the buffered output to target as input + /// copy copyMax bytes of the buffered output to target as input - //! \brief Copy bytes from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param copyMax the number of bytes to copy - //! \param channel the channel on which the transfer should occur - //! \return the number of bytes copied during the call. - //! \details CopyTo copies bytes from this object to the destination. The bytes are not removed from this object. - //! \details The function always returns copyMax. If an accurate count is needed, then use CopyRangeTo2(). + /// \brief Copy bytes from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param copyMax the number of bytes to copy + /// \param channel the channel on which the transfer should occur + /// \return the number of bytes copied during the call. + /// \details CopyTo copies bytes from this object to the destination. The bytes are not removed from this object. + /// \details The function always returns copyMax. If an accurate count is needed, then use CopyRangeTo2(). lword CopyTo(BufferedTransformation &target, lword copyMax=LWORD_MAX, const std::string &channel=DEFAULT_CHANNEL) const {return CopyRangeTo(target, 0, copyMax, channel);} - //! \brief Copy bytes from this object using an index to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param position the 0-based index of the byte stream to begin the copying - //! \param copyMax the number of bytes to copy - //! \param channel the channel on which the transfer should occur - //! \return the number of bytes copied during the call. - //! \details CopyTo copies bytes from this object to the destination. The bytes remain in this - //! object. Copying begins at the index position in the current stream, and not from an absolute - //! position in the stream. - //! \details The function returns the new position in the stream after transferring the bytes starting at the index. + /// \brief Copy bytes from this object using an index to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param position the 0-based index of the byte stream to begin the copying + /// \param copyMax the number of bytes to copy + /// \param channel the channel on which the transfer should occur + /// \return the number of bytes copied during the call. + /// \details CopyTo copies bytes from this object to the destination. The bytes remain in this + /// object. Copying begins at the index position in the current stream, and not from an absolute + /// position in the stream. + /// \details The function returns the new position in the stream after transferring the bytes starting at the index. lword CopyRangeTo(BufferedTransformation &target, lword position, lword copyMax=LWORD_MAX, const std::string &channel=DEFAULT_CHANNEL) const {lword i = position; CopyRangeTo2(target, i, i+copyMax, channel); return i-position;} //@} - //! \name RETRIEVAL OF MULTIPLE MESSAGES + /// \name RETRIEVAL OF MULTIPLE MESSAGES //@{ - //! \brief Provides the number of bytes ready for retrieval - //! \return the number of bytes ready for retrieval + /// \brief Provides the number of bytes ready for retrieval + /// \return the number of bytes ready for retrieval virtual lword TotalBytesRetrievable() const; - //! \brief Provides the number of meesages processed by this object - //! \return the number of meesages processed by this object - //! \details NumberOfMessages returns number of times MessageEnd() has been - //! received minus messages retrieved or skipped + /// \brief Provides the number of meesages processed by this object + /// \return the number of meesages processed by this object + /// \details NumberOfMessages returns number of times MessageEnd() has been + /// received minus messages retrieved or skipped virtual unsigned int NumberOfMessages() const; - //! \brief Determines if any messages are available for retrieval - //! \returns true if NumberOfMessages() > 0, false otherwise - //! \details AnyMessages returns true if NumberOfMessages() > 0 + /// \brief Determines if any messages are available for retrieval + /// \returns true if NumberOfMessages() > 0, false otherwise + /// \details AnyMessages returns true if NumberOfMessages() > 0 virtual bool AnyMessages() const; - //! \brief Start retrieving the next message - //! \return true if a message is ready for retrieval - //! \details GetNextMessage() returns true if a message is ready for retrieval; false - //! if no more messages exist or this message is not completely retrieved. + /// \brief Start retrieving the next message + /// \return true if a message is ready for retrieval + /// \details GetNextMessage() returns true if a message is ready for retrieval; false + /// if no more messages exist or this message is not completely retrieved. virtual bool GetNextMessage(); - //! \brief Skip a number of meessages - //! \return 0 if the requested number of messages was skipped, non-0 otherwise - //! \details SkipMessages() skips count number of messages. If there is an AttachedTransformation() - //! then SkipMessages() is called on the attached transformation. If there is no attached - //! transformation, then count number of messages are sent to TheBitBucket() using TransferMessagesTo(). + /// \brief Skip a number of meessages + /// \return 0 if the requested number of messages was skipped, non-0 otherwise + /// \details SkipMessages() skips count number of messages. If there is an AttachedTransformation() + /// then SkipMessages() is called on the attached transformation. If there is no attached + /// transformation, then count number of messages are sent to TheBitBucket() using TransferMessagesTo(). virtual unsigned int SkipMessages(unsigned int count=UINT_MAX); - //! \brief Transfer messages from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param count the number of messages to transfer - //! \param channel the channel on which the transfer should occur - //! \return the number of bytes that remain in the current transfer block (i.e., bytes not transferred) - //! \details TransferMessagesTo2() removes messages from this object and moves them to the destination. - //! If all bytes are not transferred for a message, then processing stops and the number of remaining - //! bytes is returned. TransferMessagesTo() does not proceed to the next message. - //! \details A return value of 0 indicates all messages were successfully transferred. + /// \brief Transfer messages from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param count the number of messages to transfer + /// \param channel the channel on which the transfer should occur + /// \return the number of bytes that remain in the current transfer block (i.e., bytes not transferred) + /// \details TransferMessagesTo2() removes messages from this object and moves them to the destination. + /// If all bytes are not transferred for a message, then processing stops and the number of remaining + /// bytes is returned. TransferMessagesTo() does not proceed to the next message. + /// \details A return value of 0 indicates all messages were successfully transferred. unsigned int TransferMessagesTo(BufferedTransformation &target, unsigned int count=UINT_MAX, const std::string &channel=DEFAULT_CHANNEL) {TransferMessagesTo2(target, count, channel); return count;} - //! \brief Copy messages from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param count the number of messages to transfer - //! \param channel the channel on which the transfer should occur - //! \return the number of bytes that remain in the current transfer block (i.e., bytes not transferred) - //! \details CopyMessagesTo copies messages from this object and copies them to the destination. - //! If all bytes are not transferred for a message, then processing stops and the number of remaining - //! bytes is returned. CopyMessagesTo() does not proceed to the next message. - //! \details A return value of 0 indicates all messages were successfully copied. + /// \brief Copy messages from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param count the number of messages to transfer + /// \param channel the channel on which the transfer should occur + /// \return the number of bytes that remain in the current transfer block (i.e., bytes not transferred) + /// \details CopyMessagesTo copies messages from this object and copies them to the destination. + /// If all bytes are not transferred for a message, then processing stops and the number of remaining + /// bytes is returned. CopyMessagesTo() does not proceed to the next message. + /// \details A return value of 0 indicates all messages were successfully copied. unsigned int CopyMessagesTo(BufferedTransformation &target, unsigned int count=UINT_MAX, const std::string &channel=DEFAULT_CHANNEL) const; - //! \brief Skip all messages in the series + /// \brief Skip all messages in the series virtual void SkipAll(); - //! \brief Transfer all bytes from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param channel the channel on which the transfer should occur - //! \details TransferMessagesTo2() removes messages from this object and moves them to the destination. - //! Internally TransferAllTo() calls TransferAllTo2(). + /// \brief Transfer all bytes from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param channel the channel on which the transfer should occur + /// \details TransferMessagesTo2() removes messages from this object and moves them to the destination. + /// Internally TransferAllTo() calls TransferAllTo2(). void TransferAllTo(BufferedTransformation &target, const std::string &channel=DEFAULT_CHANNEL) {TransferAllTo2(target, channel);} - //! \brief Copy messages from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param channel the channel on which the transfer should occur - //! \details CopyAllTo copies messages from this object and copies them to the destination. + /// \brief Copy messages from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param channel the channel on which the transfer should occur + /// \details CopyAllTo copies messages from this object and copies them to the destination. void CopyAllTo(BufferedTransformation &target, const std::string &channel=DEFAULT_CHANNEL) const; - //! \brief Retrieve the next message in a series - //! \return true if a message was retreved, false otherwise - //! \details Internally, the base class implementation returns false. + /// \brief Retrieve the next message in a series + /// \return true if a message was retreved, false otherwise + /// \details Internally, the base class implementation returns false. virtual bool GetNextMessageSeries() {return false;} - //! \brief Provides the number of messages in a series - //! \return the number of messages in this series + /// \brief Provides the number of messages in a series + /// \return the number of messages in this series virtual unsigned int NumberOfMessagesInThisSeries() const {return NumberOfMessages();} - //! \brief Provides the number of messages in a series - //! \return the number of messages in this series + /// \brief Provides the number of messages in a series + /// \return the number of messages in this series virtual unsigned int NumberOfMessageSeries() const {return 0;} //@} - //! \name NON-BLOCKING TRANSFER OF OUTPUT + /// \name NON-BLOCKING TRANSFER OF OUTPUT //@{ // upon return, byteCount contains number of bytes that have finished being transferred, // and returns the number of bytes left in the current transfer block - //! \brief Transfer bytes from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param byteCount the number of bytes to transfer - //! \param channel the channel on which the transfer should occur - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the transfer block (i.e., bytes not transferred) - //! \details TransferTo() removes bytes from this object and moves them to the destination. - //! Transfer begins at the index position in the current stream, and not from an absolute - //! position in the stream. - //! \details byteCount is an \a IN and \a OUT parameter. When the call is made, - //! byteCount is the requested size of the transfer. When the call returns, byteCount is - //! the number of bytes that were transferred. + /// \brief Transfer bytes from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param byteCount the number of bytes to transfer + /// \param channel the channel on which the transfer should occur + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the transfer block (i.e., bytes not transferred) + /// \details TransferTo() removes bytes from this object and moves them to the destination. + /// Transfer begins at the index position in the current stream, and not from an absolute + /// position in the stream. + /// \details byteCount is an \a IN and \a OUT parameter. When the call is made, + /// byteCount is the requested size of the transfer. When the call returns, byteCount is + /// the number of bytes that were transferred. virtual size_t TransferTo2(BufferedTransformation &target, lword &byteCount, const std::string &channel=DEFAULT_CHANNEL, bool blocking=true) =0; // upon return, begin contains the start position of data yet to be finished copying, // and returns the number of bytes left in the current transfer block - //! \brief Copy bytes from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param begin the 0-based index of the first byte to copy in the stream - //! \param end the 0-based index of the last byte to copy in the stream - //! \param channel the channel on which the transfer should occur - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the copy block (i.e., bytes not copied) - //! \details CopyRangeTo2 copies bytes from this object to the destination. The bytes are not - //! removed from this object. Copying begins at the index position in the current stream, and - //! not from an absolute position in the stream. - //! \details begin is an \a IN and \a OUT parameter. When the call is made, begin is the - //! starting position of the copy. When the call returns, begin is the position of the first - //! byte that was \a not copied (which may be different than end). begin can be used for - //! subsequent calls to CopyRangeTo2(). + /// \brief Copy bytes from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param begin the 0-based index of the first byte to copy in the stream + /// \param end the 0-based index of the last byte to copy in the stream + /// \param channel the channel on which the transfer should occur + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the copy block (i.e., bytes not copied) + /// \details CopyRangeTo2 copies bytes from this object to the destination. The bytes are not + /// removed from this object. Copying begins at the index position in the current stream, and + /// not from an absolute position in the stream. + /// \details begin is an \a IN and \a OUT parameter. When the call is made, begin is the + /// starting position of the copy. When the call returns, begin is the position of the first + /// byte that was \a not copied (which may be different than end). begin can be used for + /// subsequent calls to CopyRangeTo2(). virtual size_t CopyRangeTo2(BufferedTransformation &target, lword &begin, lword end=LWORD_MAX, const std::string &channel=DEFAULT_CHANNEL, bool blocking=true) const =0; // upon return, messageCount contains number of messages that have finished being transferred, // and returns the number of bytes left in the current transfer block - //! \brief Transfer messages from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param messageCount the number of messages to transfer - //! \param channel the channel on which the transfer should occur - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the current transfer block (i.e., bytes not transferred) - //! \details TransferMessagesTo2() removes messages from this object and moves them to the destination. - //! \details messageCount is an \a IN and \a OUT parameter. When the call is made, messageCount is the - //! the number of messages requested to be transferred. When the call returns, messageCount is the - //! number of messages actually transferred. + /// \brief Transfer messages from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param messageCount the number of messages to transfer + /// \param channel the channel on which the transfer should occur + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the current transfer block (i.e., bytes not transferred) + /// \details TransferMessagesTo2() removes messages from this object and moves them to the destination. + /// \details messageCount is an \a IN and \a OUT parameter. When the call is made, messageCount is the + /// the number of messages requested to be transferred. When the call returns, messageCount is the + /// number of messages actually transferred. size_t TransferMessagesTo2(BufferedTransformation &target, unsigned int &messageCount, const std::string &channel=DEFAULT_CHANNEL, bool blocking=true); // returns the number of bytes left in the current transfer block - //! \brief Transfer all bytes from this object to another BufferedTransformation - //! \param target the destination BufferedTransformation - //! \param channel the channel on which the transfer should occur - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the current transfer block (i.e., bytes not transferred) - //! \details TransferMessagesTo2() removes messages from this object and moves them to the destination. + /// \brief Transfer all bytes from this object to another BufferedTransformation + /// \param target the destination BufferedTransformation + /// \param channel the channel on which the transfer should occur + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the current transfer block (i.e., bytes not transferred) + /// \details TransferMessagesTo2() removes messages from this object and moves them to the destination. size_t TransferAllTo2(BufferedTransformation &target, const std::string &channel=DEFAULT_CHANNEL, bool blocking=true); //@} - //! \name CHANNELS + /// \name CHANNELS //@{ - //! \brief Exception thrown when a filter does not support named channels + /// \brief Exception thrown when a filter does not support named channels struct NoChannelSupport : public NotImplemented {NoChannelSupport(const std::string &name) : NotImplemented(name + ": this object doesn't support multiple channels") {}}; - //! \brief Exception thrown when a filter does not recognize a named channel + /// \brief Exception thrown when a filter does not recognize a named channel struct InvalidChannelName : public InvalidArgument {InvalidChannelName(const std::string &name, const std::string &channel) : InvalidArgument(name + ": unexpected channel name \"" + channel + "\"") {}}; - //! \brief Input a byte for processing on a channel - //! \param channel the channel to process the data. - //! \param inByte the 8-bit byte (octet) to be processed. - //! \param blocking specifies whether the object should block when processing input. - //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the - //! number of bytes that were not processed. + /// \brief Input a byte for processing on a channel + /// \param channel the channel to process the data. + /// \param inByte the 8-bit byte (octet) to be processed. + /// \param blocking specifies whether the object should block when processing input. + /// \return 0 indicates all bytes were processed during the call. Non-0 indicates the + /// number of bytes that were not processed. size_t ChannelPut(const std::string &channel, byte inByte, bool blocking=true) {return ChannelPut(channel, &inByte, 1, blocking);} - //! \brief Input a byte buffer for processing on a channel - //! \param channel the channel to process the data - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param blocking specifies whether the object should block when processing input - //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the - //! number of bytes that were not processed. + /// \brief Input a byte buffer for processing on a channel + /// \param channel the channel to process the data + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param blocking specifies whether the object should block when processing input + /// \return 0 indicates all bytes were processed during the call. Non-0 indicates the + /// number of bytes that were not processed. size_t ChannelPut(const std::string &channel, const byte *inString, size_t length, bool blocking=true) {return ChannelPut2(channel, inString, length, 0, blocking);} - //! \brief Input multiple bytes that may be modified by callee on a channel - //! \param channel the channel to process the data. - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param blocking specifies whether the object should block when processing input - //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the - //! number of bytes that were not processed. + /// \brief Input multiple bytes that may be modified by callee on a channel + /// \param channel the channel to process the data. + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param blocking specifies whether the object should block when processing input + /// \return 0 indicates all bytes were processed during the call. Non-0 indicates the + /// number of bytes that were not processed. size_t ChannelPutModifiable(const std::string &channel, byte *inString, size_t length, bool blocking=true) {return ChannelPutModifiable2(channel, inString, length, 0, blocking);} - //! \brief Input a 16-bit word for processing on a channel. - //! \param channel the channel to process the data. - //! \param value the 16-bit value to be processed. - //! \param order the ByteOrder of the value to be processed. - //! \param blocking specifies whether the object should block when processing input. - //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the - //! number of bytes that were not processed. + /// \brief Input a 16-bit word for processing on a channel. + /// \param channel the channel to process the data. + /// \param value the 16-bit value to be processed. + /// \param order the ByteOrder of the value to be processed. + /// \param blocking specifies whether the object should block when processing input. + /// \return 0 indicates all bytes were processed during the call. Non-0 indicates the + /// number of bytes that were not processed. size_t ChannelPutWord16(const std::string &channel, word16 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true); - //! \brief Input a 32-bit word for processing on a channel. - //! \param channel the channel to process the data. - //! \param value the 32-bit value to be processed. - //! \param order the ByteOrder of the value to be processed. - //! \param blocking specifies whether the object should block when processing input. - //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the - //! number of bytes that were not processed. + /// \brief Input a 32-bit word for processing on a channel. + /// \param channel the channel to process the data. + /// \param value the 32-bit value to be processed. + /// \param order the ByteOrder of the value to be processed. + /// \param blocking specifies whether the object should block when processing input. + /// \return 0 indicates all bytes were processed during the call. Non-0 indicates the + /// number of bytes that were not processed. size_t ChannelPutWord32(const std::string &channel, word32 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true); - //! \brief Signal the end of a message - //! \param channel the channel to process the data. - //! \param propagation the number of attached transformations the ChannelMessageEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the - //! number of bytes that were not processed. - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. + /// \brief Signal the end of a message + /// \param channel the channel to process the data. + /// \param propagation the number of attached transformations the ChannelMessageEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \return 0 indicates all bytes were processed during the call. Non-0 indicates the + /// number of bytes that were not processed. + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. bool ChannelMessageEnd(const std::string &channel, int propagation=-1, bool blocking=true) {return !!ChannelPut2(channel, NULLPTR, 0, propagation < 0 ? -1 : propagation+1, blocking);} - //! \brief Input multiple bytes for processing and signal the end of a message - //! \param channel the channel to process the data. - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param propagation the number of attached transformations the ChannelPutMessageEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the block (i.e., bytes not processed) - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. + /// \brief Input multiple bytes for processing and signal the end of a message + /// \param channel the channel to process the data. + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param propagation the number of attached transformations the ChannelPutMessageEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the block (i.e., bytes not processed) + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. size_t ChannelPutMessageEnd(const std::string &channel, const byte *inString, size_t length, int propagation=-1, bool blocking=true) {return ChannelPut2(channel, inString, length, propagation < 0 ? -1 : propagation+1, blocking);} - //! \brief Request space which can be written into by the caller - //! \param channel the channel to process the data - //! \param size the requested size of the buffer - //! \return a pointer to a memroy block with length size - //! \details The purpose of this method is to help avoid extra memory allocations. - //! \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, - //! size is the requested size of the buffer. When the call returns, size is the size of - //! the array returned to the caller. - //! \details The base class implementation sets size to 0 and returns NULL. - //! \note Some objects, like ArraySink(), cannot create a space because its fixed. In the case of - //! an ArraySink(), the pointer to the array is returned and the size is remaining size. + /// \brief Request space which can be written into by the caller + /// \param channel the channel to process the data + /// \param size the requested size of the buffer + /// \return a pointer to a memroy block with length size + /// \details The purpose of this method is to help avoid extra memory allocations. + /// \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, + /// size is the requested size of the buffer. When the call returns, size is the size of + /// the array returned to the caller. + /// \details The base class implementation sets size to 0 and returns NULL. + /// \note Some objects, like ArraySink(), cannot create a space because its fixed. In the case of + /// an ArraySink(), the pointer to the array is returned and the size is remaining size. virtual byte * ChannelCreatePutSpace(const std::string &channel, size_t &size); - //! \brief Input multiple bytes for processing on a channel. - //! \param channel the channel to process the data. - //! \param inString the byte buffer to process. - //! \param length the size of the string, in bytes. - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one. - //! \param blocking specifies whether the object should block when processing input. - //! \return the number of bytes that remain in the block (i.e., bytes not processed) + /// \brief Input multiple bytes for processing on a channel. + /// \param channel the channel to process the data. + /// \param inString the byte buffer to process. + /// \param length the size of the string, in bytes. + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one. + /// \param blocking specifies whether the object should block when processing input. + /// \return the number of bytes that remain in the block (i.e., bytes not processed) virtual size_t ChannelPut2(const std::string &channel, const byte *inString, size_t length, int messageEnd, bool blocking); - //! \brief Input multiple bytes that may be modified by callee on a channel - //! \param channel the channel to process the data - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one - //! \param blocking specifies whether the object should block when processing input - //! \return the number of bytes that remain in the block (i.e., bytes not processed) + /// \brief Input multiple bytes that may be modified by callee on a channel + /// \param channel the channel to process the data + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one + /// \param blocking specifies whether the object should block when processing input + /// \return the number of bytes that remain in the block (i.e., bytes not processed) virtual size_t ChannelPutModifiable2(const std::string &channel, byte *inString, size_t length, int messageEnd, bool blocking); - //! \brief Flush buffered input and/or output on a channel - //! \param channel the channel to flush the data - //! \param hardFlush is used to indicate whether all data should be flushed - //! \param propagation the number of attached transformations the ChannelFlush() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \return true of the Flush was successful - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. + /// \brief Flush buffered input and/or output on a channel + /// \param channel the channel to flush the data + /// \param hardFlush is used to indicate whether all data should be flushed + /// \param propagation the number of attached transformations the ChannelFlush() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \return true of the Flush was successful + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. virtual bool ChannelFlush(const std::string &channel, bool hardFlush, int propagation=-1, bool blocking=true); - //! \brief Marks the end of a series of messages on a channel - //! \param channel the channel to signal the end of a series of messages - //! \param propagation the number of attached transformations the ChannelMessageSeriesEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \details Each object that receives the signal will perform its processing, decrement - //! propagation, and then pass the signal on to attached transformations if the value is not 0. - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. - //! \note There should be a MessageEnd() immediately before MessageSeriesEnd(). + /// \brief Marks the end of a series of messages on a channel + /// \param channel the channel to signal the end of a series of messages + /// \param propagation the number of attached transformations the ChannelMessageSeriesEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \details Each object that receives the signal will perform its processing, decrement + /// propagation, and then pass the signal on to attached transformations if the value is not 0. + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. + /// \note There should be a MessageEnd() immediately before MessageSeriesEnd(). virtual bool ChannelMessageSeriesEnd(const std::string &channel, int propagation=-1, bool blocking=true); - //! \brief Sets the default retrieval channel - //! \param channel the channel to signal the end of a series of messages - //! \note this function may not be implemented in all objects that should support it. + /// \brief Sets the default retrieval channel + /// \param channel the channel to signal the end of a series of messages + /// \note this function may not be implemented in all objects that should support it. virtual void SetRetrievalChannel(const std::string &channel); //@} - //! \name ATTACHMENT - //! \details Some BufferedTransformation objects (e.g. Filter objects) allow other BufferedTransformation objects to be - //! attached. When this is done, the first object instead of buffering its output, sends that output to the attached - //! object as input. The entire attachment chain is deleted when the anchor object is destructed. + /// \name ATTACHMENT + /// \details Some BufferedTransformation objects (e.g. Filter objects) allow other BufferedTransformation objects to be + /// attached. When this is done, the first object instead of buffering its output, sends that output to the attached + /// object as input. The entire attachment chain is deleted when the anchor object is destructed. //@{ - //! \brief Determines whether the object allows attachment - //! \return true if the object allows an attachment, false otherwise - //! \details Sources and Filters will returns true, while Sinks and other objects will return false. + /// \brief Determines whether the object allows attachment + /// \return true if the object allows an attachment, false otherwise + /// \details Sources and Filters will returns true, while Sinks and other objects will return false. virtual bool Attachable() {return false;} - //! \brief Returns the object immediately attached to this object - //! \return the attached transformation - //! \details AttachedTransformation() returns NULL if there is no attachment. The non-const - //! version of AttachedTransformation() always returns NULL. + /// \brief Returns the object immediately attached to this object + /// \return the attached transformation + /// \details AttachedTransformation() returns NULL if there is no attachment. The non-const + /// version of AttachedTransformation() always returns NULL. virtual BufferedTransformation *AttachedTransformation() {CRYPTOPP_ASSERT(!Attachable()); return NULLPTR;} - //! \brief Returns the object immediately attached to this object - //! \return the attached transformation - //! \details AttachedTransformation() returns NULL if there is no attachment. The non-const - //! version of AttachedTransformation() always returns NULL. + /// \brief Returns the object immediately attached to this object + /// \return the attached transformation + /// \details AttachedTransformation() returns NULL if there is no attachment. The non-const + /// version of AttachedTransformation() always returns NULL. virtual const BufferedTransformation *AttachedTransformation() const {return const_cast(this)->AttachedTransformation();} - //! \brief Delete the current attachment chain and attach a new one - //! \param newAttachment the new BufferedTransformation to attach - //! \throws NotImplemented - //! \details Detach() deletes the current attachment chain and replace it with an optional newAttachment - //! \details If a derived class does not override Detach(), then the base class throws - //! NotImplemented. + /// \brief Delete the current attachment chain and attach a new one + /// \param newAttachment the new BufferedTransformation to attach + /// \throws NotImplemented + /// \details Detach() deletes the current attachment chain and replace it with an optional newAttachment + /// \details If a derived class does not override Detach(), then the base class throws + /// NotImplemented. virtual void Detach(BufferedTransformation *newAttachment = NULLPTR) { CRYPTOPP_UNUSED(newAttachment); CRYPTOPP_ASSERT(!Attachable()); throw NotImplemented("BufferedTransformation: this object is not attachable"); } - //! \brief Add newAttachment to the end of attachment chain - //! \param newAttachment the attachment to add to the end of the chain + /// \brief Add newAttachment to the end of attachment chain + /// \param newAttachment the attachment to add to the end of the chain virtual void Attach(BufferedTransformation *newAttachment); //@} protected: - //! \brief Decrements the propagation count while clamping at 0 - //! \return the decremented propagation or 0 + /// \brief Decrements the propagation count while clamping at 0 + /// \return the decremented propagation or 0 static int DecrementPropagation(int propagation) {return propagation != 0 ? propagation - 1 : 0;} @@ -2158,16 +2158,16 @@ private: byte m_buf[4]; // for ChannelPutWord16 and ChannelPutWord32, to ensure buffer isn't deallocated before non-blocking operation completes }; -//! \brief An input discarding BufferedTransformation -//! \return a reference to a BufferedTransformation object that discards all input +/// \brief An input discarding BufferedTransformation +/// \return a reference to a BufferedTransformation object that discards all input CRYPTOPP_DLL BufferedTransformation & TheBitBucket(); -//! \class CryptoMaterial -//! \brief Interface for crypto material, such as public and private keys, and crypto parameters +/// \class CryptoMaterial +/// \brief Interface for crypto material, such as public and private keys, and crypto parameters class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CryptoMaterial : public NameValuePairs { public: - //! Exception thrown when invalid crypto material is detected + /// Exception thrown when invalid crypto material is detected class CRYPTOPP_DLL InvalidMaterial : public InvalidDataFormat { public: @@ -2176,97 +2176,97 @@ public: virtual ~CryptoMaterial() {} - //! \brief Assign values to this object - //! \details This function can be used to create a public key from a private key. + /// \brief Assign values to this object + /// \details This function can be used to create a public key from a private key. virtual void AssignFrom(const NameValuePairs &source) =0; - //! \brief Check this object for errors - //! \param rng a RandomNumberGenerator for objects which use randomized testing - //! \param level the level of thoroughness - //! \returns true if the tests succeed, false otherwise - //! \details There are four levels of thoroughness: - //!
    - //!
  • 0 - using this object won't cause a crash or exception - //!
  • 1 - this object will probably function, and encrypt, sign, other operations correctly - //!
  • 2 - ensure this object will function correctly, and perform reasonable security checks - //!
  • 3 - perform reasonable security checks, and do checks that may take a long time - //!
- //! \details Level 0 does not require a RandomNumberGenerator. A NullRNG() can be used for level 0. - //! Level 1 may not check for weak keys and such. Levels 2 and 3 are recommended. - //! \sa ThrowIfInvalid() + /// \brief Check this object for errors + /// \param rng a RandomNumberGenerator for objects which use randomized testing + /// \param level the level of thoroughness + /// \returns true if the tests succeed, false otherwise + /// \details There are four levels of thoroughness: + ///
    + ///
  • 0 - using this object won't cause a crash or exception + ///
  • 1 - this object will probably function, and encrypt, sign, other operations correctly + ///
  • 2 - ensure this object will function correctly, and perform reasonable security checks + ///
  • 3 - perform reasonable security checks, and do checks that may take a long time + ///
+ /// \details Level 0 does not require a RandomNumberGenerator. A NullRNG() can be used for level 0. + /// Level 1 may not check for weak keys and such. Levels 2 and 3 are recommended. + /// \sa ThrowIfInvalid() virtual bool Validate(RandomNumberGenerator &rng, unsigned int level) const =0; - //! \brief Check this object for errors - //! \param rng a RandomNumberGenerator for objects which use randomized testing - //! \param level the level of thoroughness - //! \throws InvalidMaterial - //! \details Internally, ThrowIfInvalid() calls Validate() and throws InvalidMaterial() if validation fails. - //! \sa Validate() + /// \brief Check this object for errors + /// \param rng a RandomNumberGenerator for objects which use randomized testing + /// \param level the level of thoroughness + /// \throws InvalidMaterial + /// \details Internally, ThrowIfInvalid() calls Validate() and throws InvalidMaterial() if validation fails. + /// \sa Validate() virtual void ThrowIfInvalid(RandomNumberGenerator &rng, unsigned int level) const {if (!Validate(rng, level)) throw InvalidMaterial("CryptoMaterial: this object contains invalid values");} - //! \brief Saves a key to a BufferedTransformation - //! \param bt the destination BufferedTransformation - //! \throws NotImplemented - //! \details Save() writes the material to a BufferedTransformation. - //! \details If the material is a key, then the key is written with ASN.1 DER encoding. The key - //! includes an object identifier with an algorthm id, like a subjectPublicKeyInfo. - //! \details A "raw" key without the "key info" can be saved using a key's DEREncode() method. - //! \details If a derived class does not override Save(), then the base class throws - //! NotImplemented(). + /// \brief Saves a key to a BufferedTransformation + /// \param bt the destination BufferedTransformation + /// \throws NotImplemented + /// \details Save() writes the material to a BufferedTransformation. + /// \details If the material is a key, then the key is written with ASN.1 DER encoding. The key + /// includes an object identifier with an algorthm id, like a subjectPublicKeyInfo. + /// \details A "raw" key without the "key info" can be saved using a key's DEREncode() method. + /// \details If a derived class does not override Save(), then the base class throws + /// NotImplemented(). virtual void Save(BufferedTransformation &bt) const {CRYPTOPP_UNUSED(bt); throw NotImplemented("CryptoMaterial: this object does not support saving");} - //! \brief Loads a key from a BufferedTransformation - //! \param bt the source BufferedTransformation - //! \throws KeyingErr - //! \details Load() attempts to read material from a BufferedTransformation. If the - //! material is a key that was generated outside the library, then the following - //! usually applies: - //!
    - //!
  • the key should be ASN.1 BER encoded - //!
  • the key should be a "key info" - //!
- //! \details "key info" means the key should have an object identifier with an algorthm id, - //! like a subjectPublicKeyInfo. - //! \details To read a "raw" key without the "key info", then call the key's BERDecode() method. - //! \note Load() generally does not check that the key is valid. Call Validate(), if needed. + /// \brief Loads a key from a BufferedTransformation + /// \param bt the source BufferedTransformation + /// \throws KeyingErr + /// \details Load() attempts to read material from a BufferedTransformation. If the + /// material is a key that was generated outside the library, then the following + /// usually applies: + ///
    + ///
  • the key should be ASN.1 BER encoded + ///
  • the key should be a "key info" + ///
+ /// \details "key info" means the key should have an object identifier with an algorthm id, + /// like a subjectPublicKeyInfo. + /// \details To read a "raw" key without the "key info", then call the key's BERDecode() method. + /// \note Load() generally does not check that the key is valid. Call Validate(), if needed. virtual void Load(BufferedTransformation &bt) {CRYPTOPP_UNUSED(bt); throw NotImplemented("CryptoMaterial: this object does not support loading");} - //! \brief Determines whether the object supports precomputation - //! \return true if the object supports precomputation, false otherwise - //! \sa Precompute() + /// \brief Determines whether the object supports precomputation + /// \return true if the object supports precomputation, false otherwise + /// \sa Precompute() virtual bool SupportsPrecomputation() const {return false;} - //! \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() + /// \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() virtual void Precompute(unsigned int precomputationStorage) { CRYPTOPP_UNUSED(precomputationStorage); CRYPTOPP_ASSERT(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation"); } - //! \brief Retrieve previously saved precomputation - //! \param storedPrecomputation BufferedTransformation with the saved precomputation - //! \throws NotImplemented - //! \sa SupportsPrecomputation(), Precompute() + /// \brief Retrieve previously saved precomputation + /// \param storedPrecomputation BufferedTransformation with the saved precomputation + /// \throws NotImplemented + /// \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 - //! \sa SupportsPrecomputation(), Precompute() + /// \brief Save precomputation for later use + /// \param storedPrecomputation BufferedTransformation to write the precomputation + /// \throws NotImplemented + /// \sa SupportsPrecomputation(), Precompute() virtual void SavePrecomputation(BufferedTransformation &storedPrecomputation) const {CRYPTOPP_UNUSED(storedPrecomputation); CRYPTOPP_ASSERT(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation");} - //! \brief Perform a quick sanity check - //! \details DoQuickSanityCheck() is for internal library use, and it should not be called by library users. + /// \brief Perform a quick sanity check + /// \details DoQuickSanityCheck() is for internal library use, and it should not be called by library users. void DoQuickSanityCheck() const {ThrowIfInvalid(NullRNG(), 0);} #if (defined(__SUNPRO_CC) && __SUNPRO_CC < 0x590) @@ -2275,76 +2275,76 @@ public: #endif }; -//! \class GeneratableCryptoMaterial -//! \brief Interface for generatable crypto material, such as private keys and crypto parameters +/// \class GeneratableCryptoMaterial +/// \brief Interface for generatable crypto material, such as private keys and crypto parameters class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE GeneratableCryptoMaterial : virtual public CryptoMaterial { public: virtual ~GeneratableCryptoMaterial() {} - //! \brief Generate a random key or crypto parameters - //! \param rng a RandomNumberGenerator to produce keying material - //! \param params additional initialization parameters - //! \throws KeyingErr if a key can't be generated or algorithm parameters are invalid - //! \details If a derived class does not override GenerateRandom(), then the base class throws - //! NotImplemented. + /// \brief Generate a random key or crypto parameters + /// \param rng a RandomNumberGenerator to produce keying material + /// \param params additional initialization parameters + /// \throws KeyingErr if a key can't be generated or algorithm parameters are invalid + /// \details If a derived class does not override GenerateRandom(), then the base class throws + /// NotImplemented. virtual void GenerateRandom(RandomNumberGenerator &rng, const NameValuePairs ¶ms = g_nullNameValuePairs) { CRYPTOPP_UNUSED(rng); CRYPTOPP_UNUSED(params); throw NotImplemented("GeneratableCryptoMaterial: this object does not support key/parameter generation"); } - //! \brief Generate a random key or crypto parameters - //! \param rng a RandomNumberGenerator to produce keying material - //! \param keySize the size of the key, in bits - //! \throws KeyingErr if a key can't be generated or algorithm parameters are invalid - //! \details GenerateRandomWithKeySize calls GenerateRandom() with a NameValuePairs - //! object with only "KeySize" + /// \brief Generate a random key or crypto parameters + /// \param rng a RandomNumberGenerator to produce keying material + /// \param keySize the size of the key, in bits + /// \throws KeyingErr if a key can't be generated or algorithm parameters are invalid + /// \details GenerateRandomWithKeySize calls GenerateRandom() with a NameValuePairs + /// object with only "KeySize" void GenerateRandomWithKeySize(RandomNumberGenerator &rng, unsigned int keySize); }; -//! \brief Interface for public keys +/// \brief Interface for public keys class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PublicKey : virtual public CryptoMaterial { }; -//! \brief Interface for private keys +/// \brief Interface for private keys class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PrivateKey : public GeneratableCryptoMaterial { }; -//! \brief Interface for crypto prameters +/// \brief Interface for crypto prameters class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CryptoParameters : public GeneratableCryptoMaterial { }; -//! \brief Interface for asymmetric algorithms +/// \brief Interface for asymmetric algorithms class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AsymmetricAlgorithm : public Algorithm { public: virtual ~AsymmetricAlgorithm() {} - //! \brief Retrieves a reference to CryptoMaterial - //! \return a reference to the crypto material + /// \brief Retrieves a reference to CryptoMaterial + /// \return a reference to the crypto material virtual CryptoMaterial & AccessMaterial() =0; - //! \brief Retrieves a reference to CryptoMaterial - //! \return a const reference to the crypto material + /// \brief Retrieves a reference to CryptoMaterial + /// \return a const reference to the crypto material virtual const CryptoMaterial & GetMaterial() const =0; - //! \brief Loads this object from a BufferedTransformation - //! \param bt a BufferedTransformation object - //! \deprecated for backwards compatibility, calls AccessMaterial().Load(bt) + /// \brief Loads this object from a BufferedTransformation + /// \param bt a BufferedTransformation object + /// \deprecated for backwards compatibility, calls AccessMaterial().Load(bt) void BERDecode(BufferedTransformation &bt) {AccessMaterial().Load(bt);} - //! \brief Saves this object to a BufferedTransformation - //! \param bt a BufferedTransformation object - //! \deprecated for backwards compatibility, calls GetMaterial().Save(bt) + /// \brief Saves this object to a BufferedTransformation + /// \param bt a BufferedTransformation object + /// \deprecated for backwards compatibility, calls GetMaterial().Save(bt) void DEREncode(BufferedTransformation &bt) const {GetMaterial().Save(bt);} }; -//! \brief Interface for asymmetric algorithms using public keys +/// \brief Interface for asymmetric algorithms using public keys class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PublicKeyAlgorithm : public AsymmetricAlgorithm { public: @@ -2352,213 +2352,213 @@ public: // VC60 workaround: no co-variant return type - //! \brief Retrieves a reference to a Public Key - //! \return a reference to the public key + /// \brief Retrieves a reference to a Public Key + /// \return a reference to the public key CryptoMaterial & AccessMaterial() {return AccessPublicKey();} - //! \brief Retrieves a reference to a Public Key - //! \return a const reference the public key + /// \brief Retrieves a reference to a Public Key + /// \return a const reference the public key const CryptoMaterial & GetMaterial() const {return GetPublicKey();} - //! \brief Retrieves a reference to a Public Key - //! \return a reference to the public key + /// \brief Retrieves a reference to a Public Key + /// \return a reference to the public key virtual PublicKey & AccessPublicKey() =0; - //! \brief Retrieves a reference to a Public Key - //! \return a const reference the public key + /// \brief Retrieves a reference to a Public Key + /// \return a const reference the public key virtual const PublicKey & GetPublicKey() const {return const_cast(this)->AccessPublicKey();} }; -//! \brief Interface for asymmetric algorithms using private keys +/// \brief Interface for asymmetric algorithms using private keys class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PrivateKeyAlgorithm : public AsymmetricAlgorithm { public: virtual ~PrivateKeyAlgorithm() {} - //! \brief Retrieves a reference to a Private Key - //! \return a reference the private key + /// \brief Retrieves a reference to a Private Key + /// \return a reference the private key CryptoMaterial & AccessMaterial() {return AccessPrivateKey();} - //! \brief Retrieves a reference to a Private Key - //! \return a const reference the private key + /// \brief Retrieves a reference to a Private Key + /// \return a const reference the private key const CryptoMaterial & GetMaterial() const {return GetPrivateKey();} - //! \brief Retrieves a reference to a Private Key - //! \return a reference the private key + /// \brief Retrieves a reference to a Private Key + /// \return a reference the private key virtual PrivateKey & AccessPrivateKey() =0; - //! \brief Retrieves a reference to a Private Key - //! \return a const reference the private key + /// \brief Retrieves a reference to a Private Key + /// \return a const reference the private key virtual const PrivateKey & GetPrivateKey() const {return const_cast(this)->AccessPrivateKey();} }; -//! \brief Interface for key agreement algorithms +/// \brief Interface for key agreement algorithms class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE KeyAgreementAlgorithm : public AsymmetricAlgorithm { public: virtual ~KeyAgreementAlgorithm() {} - //! \brief Retrieves a reference to Crypto Parameters - //! \return a reference the crypto parameters + /// \brief Retrieves a reference to Crypto Parameters + /// \return a reference the crypto parameters CryptoMaterial & AccessMaterial() {return AccessCryptoParameters();} - //! \brief Retrieves a reference to Crypto Parameters - //! \return a const reference the crypto parameters + /// \brief Retrieves a reference to Crypto Parameters + /// \return a const reference the crypto parameters const CryptoMaterial & GetMaterial() const {return GetCryptoParameters();} - //! \brief Retrieves a reference to Crypto Parameters - //! \return a reference the crypto parameters + /// \brief Retrieves a reference to Crypto Parameters + /// \return a reference the crypto parameters virtual CryptoParameters & AccessCryptoParameters() =0; - //! \brief Retrieves a reference to Crypto Parameters - //! \return a const reference the crypto parameters + /// \brief Retrieves a reference to Crypto Parameters + /// \return a const reference the crypto parameters virtual const CryptoParameters & GetCryptoParameters() const {return const_cast(this)->AccessCryptoParameters();} }; -//! \brief Interface for public-key encryptors and decryptors -//! \details This class provides an interface common to encryptors and decryptors -//! for querying their plaintext and ciphertext lengths. +/// \brief Interface for public-key encryptors and decryptors +/// \details This class provides an interface common to encryptors and decryptors +/// for querying their plaintext and ciphertext lengths. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_CryptoSystem { public: virtual ~PK_CryptoSystem() {} - //! \brief Provides the maximum length of plaintext for a given ciphertext length - //! \return the maximum size of the plaintext, in bytes - //! \details This function returns 0 if ciphertextLength is not valid (too long or too short). + /// \brief Provides the maximum length of plaintext for a given ciphertext length + /// \return the maximum size of the plaintext, in bytes + /// \details This function returns 0 if ciphertextLength is not valid (too long or too short). virtual size_t MaxPlaintextLength(size_t ciphertextLength) const =0; - //! \brief Calculate the length of ciphertext given length of plaintext - //! \return the maximum size of the ciphertext, in bytes - //! \details This function returns 0 if plaintextLength is not valid (too long). + /// \brief Calculate the length of ciphertext given length of plaintext + /// \return the maximum size of the ciphertext, in bytes + /// \details This function returns 0 if plaintextLength is not valid (too long). virtual size_t CiphertextLength(size_t plaintextLength) const =0; - //! \brief Determines whether this object supports the use of a named parameter - //! \param name the name of the parameter - //! \return true if the parameter name is supported, false otherwise - //! \details Some possible parameter names: EncodingParameters(), KeyDerivationParameters() - //! and others Parameters listed in argnames.h + /// \brief Determines whether this object supports the use of a named parameter + /// \param name the name of the parameter + /// \return true if the parameter name is supported, false otherwise + /// \details Some possible parameter names: EncodingParameters(), KeyDerivationParameters() + /// and others Parameters listed in argnames.h virtual bool ParameterSupported(const char *name) const =0; - //! \brief Provides the fixed ciphertext length, if one exists - //! \return the fixed ciphertext length if one exists, otherwise 0 - //! \details "Fixed" here means length of ciphertext does not depend on length of plaintext. - //! In this case, it usually does depend on the key length. + /// \brief Provides the fixed ciphertext length, if one exists + /// \return the fixed ciphertext length if one exists, otherwise 0 + /// \details "Fixed" here means length of ciphertext does not depend on length of plaintext. + /// In this case, it usually does depend on the key length. virtual size_t FixedCiphertextLength() const {return 0;} - //! \brief Provides the maximum plaintext length given a fixed ciphertext length - //! \return maximum plaintext length given the fixed ciphertext length, if one exists, - //! otherwise return 0. - //! \details FixedMaxPlaintextLength(0 returns the maximum plaintext length given the fixed ciphertext - //! length, if one exists, otherwise return 0. + /// \brief Provides the maximum plaintext length given a fixed ciphertext length + /// \return maximum plaintext length given the fixed ciphertext length, if one exists, + /// otherwise return 0. + /// \details FixedMaxPlaintextLength(0 returns the maximum plaintext length given the fixed ciphertext + /// length, if one exists, otherwise return 0. virtual size_t FixedMaxPlaintextLength() const {return 0;} }; -//! \class PK_Encryptor -//! \brief Interface for public-key encryptors +/// \class PK_Encryptor +/// \brief Interface for public-key encryptors class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Encryptor : public PK_CryptoSystem, public PublicKeyAlgorithm { public: - //! \brief Exception thrown when trying to encrypt plaintext of invalid length + /// \brief Exception thrown when trying to encrypt plaintext of invalid length class CRYPTOPP_DLL InvalidPlaintextLength : public Exception { public: InvalidPlaintextLength() : Exception(OTHER_ERROR, "PK_Encryptor: invalid plaintext length") {} }; - //! \brief Encrypt a byte string - //! \param rng a RandomNumberGenerator derived class - //! \param plaintext the plaintext byte buffer - //! \param plaintextLength the size of the plaintext byte buffer - //! \param ciphertext a byte buffer to hold the encrypted string - //! \param parameters a set of NameValuePairs to initialize this object - //! \pre CiphertextLength(plaintextLength) != 0 ensures the plaintext isn't too large - //! \pre COUNTOF(ciphertext) == CiphertextLength(plaintextLength) ensures the output - //! byte buffer is large enough. - //! \sa PK_Decryptor + /// \brief Encrypt a byte string + /// \param rng a RandomNumberGenerator derived class + /// \param plaintext the plaintext byte buffer + /// \param plaintextLength the size of the plaintext byte buffer + /// \param ciphertext a byte buffer to hold the encrypted string + /// \param parameters a set of NameValuePairs to initialize this object + /// \pre CiphertextLength(plaintextLength) != 0 ensures the plaintext isn't too large + /// \pre COUNTOF(ciphertext) == CiphertextLength(plaintextLength) ensures the output + /// byte buffer is large enough. + /// \sa PK_Decryptor virtual void Encrypt(RandomNumberGenerator &rng, const byte *plaintext, size_t plaintextLength, byte *ciphertext, const NameValuePairs ¶meters = g_nullNameValuePairs) const =0; - //! \brief Create a new encryption filter - //! \param rng a RandomNumberGenerator derived class - //! \param attachment an attached transformation - //! \param parameters a set of NameValuePairs to initialize this object - //! \details \p attachment can be \p NULL. The caller is responsible for deleting the returned pointer. - //! Encoding parameters should be passed in the "EP" channel. + /// \brief Create a new encryption filter + /// \param rng a RandomNumberGenerator derived class + /// \param attachment an attached transformation + /// \param parameters a set of NameValuePairs to initialize this object + /// \details \p attachment can be \p NULL. The caller is responsible for deleting the returned pointer. + /// Encoding parameters should be passed in the "EP" channel. virtual BufferedTransformation * CreateEncryptionFilter(RandomNumberGenerator &rng, BufferedTransformation *attachment=NULLPTR, const NameValuePairs ¶meters = g_nullNameValuePairs) const; }; -//! \class PK_Decryptor -//! \brief Interface for public-key decryptors +/// \class PK_Decryptor +/// \brief Interface for public-key decryptors class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Decryptor : public PK_CryptoSystem, public PrivateKeyAlgorithm { public: virtual ~PK_Decryptor() {} - //! \brief Decrypt a byte string - //! \param rng a RandomNumberGenerator derived class - //! \param ciphertext the encrypted byte buffer - //! \param ciphertextLength the size of the encrypted byte buffer - //! \param plaintext a byte buffer to hold the decrypted string - //! \param parameters a set of NameValuePairs to initialize this object - //! \return the result of the decryption operation - //! \details If DecodingResult::isValidCoding is true, then DecodingResult::messageLength - //! is valid and holds the the actual length of the plaintext recovered. The result is undefined - //! if decryption failed. If DecodingResult::isValidCoding is false, then DecodingResult::messageLength - //! is undefined. - //! \pre COUNTOF(plaintext) == MaxPlaintextLength(ciphertextLength) ensures the output - //! byte buffer is large enough - //! \sa PK_Encryptor + /// \brief Decrypt a byte string + /// \param rng a RandomNumberGenerator derived class + /// \param ciphertext the encrypted byte buffer + /// \param ciphertextLength the size of the encrypted byte buffer + /// \param plaintext a byte buffer to hold the decrypted string + /// \param parameters a set of NameValuePairs to initialize this object + /// \return the result of the decryption operation + /// \details If DecodingResult::isValidCoding is true, then DecodingResult::messageLength + /// is valid and holds the the actual length of the plaintext recovered. The result is undefined + /// if decryption failed. If DecodingResult::isValidCoding is false, then DecodingResult::messageLength + /// is undefined. + /// \pre COUNTOF(plaintext) == MaxPlaintextLength(ciphertextLength) ensures the output + /// byte buffer is large enough + /// \sa PK_Encryptor virtual DecodingResult Decrypt(RandomNumberGenerator &rng, const byte *ciphertext, size_t ciphertextLength, byte *plaintext, const NameValuePairs ¶meters = g_nullNameValuePairs) const =0; - //! \brief Create a new decryption filter - //! \param rng a RandomNumberGenerator derived class - //! \param attachment an attached transformation - //! \param parameters a set of NameValuePairs to initialize this object - //! \return the newly created decryption filter - //! \note the caller is responsible for deleting the returned pointer + /// \brief Create a new decryption filter + /// \param rng a RandomNumberGenerator derived class + /// \param attachment an attached transformation + /// \param parameters a set of NameValuePairs to initialize this object + /// \return the newly created decryption filter + /// \note the caller is responsible for deleting the returned pointer virtual BufferedTransformation * CreateDecryptionFilter(RandomNumberGenerator &rng, BufferedTransformation *attachment=NULLPTR, const NameValuePairs ¶meters = g_nullNameValuePairs) const; - //! \brief Decrypt a fixed size ciphertext - //! \param rng a RandomNumberGenerator derived class - //! \param ciphertext the encrypted byte buffer - //! \param plaintext a byte buffer to hold the decrypted string - //! \param parameters a set of NameValuePairs to initialize this object - //! \return the result of the decryption operation - //! \details If DecodingResult::isValidCoding is true, then DecodingResult::messageLength - //! is valid and holds the the actual length of the plaintext recovered. The result is undefined - //! if decryption failed. If DecodingResult::isValidCoding is false, then DecodingResult::messageLength - //! is undefined. - //! \pre COUNTOF(plaintext) == MaxPlaintextLength(ciphertextLength) ensures the output - //! byte buffer is large enough - //! \sa PK_Encryptor + /// \brief Decrypt a fixed size ciphertext + /// \param rng a RandomNumberGenerator derived class + /// \param ciphertext the encrypted byte buffer + /// \param plaintext a byte buffer to hold the decrypted string + /// \param parameters a set of NameValuePairs to initialize this object + /// \return the result of the decryption operation + /// \details If DecodingResult::isValidCoding is true, then DecodingResult::messageLength + /// is valid and holds the the actual length of the plaintext recovered. The result is undefined + /// if decryption failed. If DecodingResult::isValidCoding is false, then DecodingResult::messageLength + /// is undefined. + /// \pre COUNTOF(plaintext) == MaxPlaintextLength(ciphertextLength) ensures the output + /// byte buffer is large enough + /// \sa PK_Encryptor DecodingResult FixedLengthDecrypt(RandomNumberGenerator &rng, const byte *ciphertext, byte *plaintext, const NameValuePairs ¶meters = g_nullNameValuePairs) const {return Decrypt(rng, ciphertext, FixedCiphertextLength(), plaintext, parameters);} }; -//! \class PK_SignatureScheme -//! \brief Interface for public-key signers and verifiers -//! \details This class provides an interface common to signers and verifiers for querying scheme properties -//! \sa DL_SignatureSchemeBase, TF_SignatureSchemeBase, DL_SignerBase, TF_SignerBase +/// \class PK_SignatureScheme +/// \brief Interface for public-key signers and verifiers +/// \details This class provides an interface common to signers and verifiers for querying scheme properties +/// \sa DL_SignatureSchemeBase, TF_SignatureSchemeBase, DL_SignerBase, TF_SignerBase class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_SignatureScheme { public: - //! \class InvalidKeyLength - //! \brief Exception throw when the private or public key has a length that can't be used - //! \details InvalidKeyLength() may be thrown by any function in this class if the private - //! or public key has a length that can't be used + /// \class InvalidKeyLength + /// \brief Exception throw when the private or public key has a length that can't be used + /// \details InvalidKeyLength() may be thrown by any function in this class if the private + /// or public key has a length that can't be used class CRYPTOPP_DLL InvalidKeyLength : public Exception { public: InvalidKeyLength(const std::string &message) : Exception(OTHER_ERROR, message) {} }; - //! \class KeyTooShort - //! \brief Exception throw when the private or public key is too short to sign or verify - //! \details KeyTooShort() may be thrown by any function in this class if the private or public - //! key is too short to sign or verify anything + /// \class KeyTooShort + /// \brief Exception throw when the private or public key is too short to sign or verify + /// \details KeyTooShort() may be thrown by any function in this class if the private or public + /// key is too short to sign or verify anything class CRYPTOPP_DLL KeyTooShort : public InvalidKeyLength { public: @@ -2567,68 +2567,68 @@ public: virtual ~PK_SignatureScheme() {} - //! \brief Provides the signature length if it only depends on the key - //! \return the signature length if it only depends on the key, in bytes - //! \details SignatureLength() returns the signature length if it only depends on the key, otherwise 0. + /// \brief Provides the signature length if it only depends on the key + /// \return the signature length if it only depends on the key, in bytes + /// \details SignatureLength() returns the signature length if it only depends on the key, otherwise 0. virtual size_t SignatureLength() const =0; - //! \brief Provides the maximum signature length produced given the length of the recoverable message part - //! \param recoverablePartLength the length of the recoverable message part, in bytes - //! \return the maximum signature length produced for a given length of recoverable message part, in bytes - //! \details MaxSignatureLength() returns the maximum signature length produced given the length of the - //! recoverable message part. + /// \brief Provides the maximum signature length produced given the length of the recoverable message part + /// \param recoverablePartLength the length of the recoverable message part, in bytes + /// \return the maximum signature length produced for a given length of recoverable message part, in bytes + /// \details MaxSignatureLength() returns the maximum signature length produced given the length of the + /// recoverable message part. virtual size_t MaxSignatureLength(size_t recoverablePartLength = 0) const {CRYPTOPP_UNUSED(recoverablePartLength); return SignatureLength();} - //! \brief Provides the length of longest message that can be recovered - //! \return the length of longest message that can be recovered, in bytes - //! \details MaxRecoverableLength() returns the length of longest message that can be recovered, or 0 if - //! this signature scheme does not support message recovery. + /// \brief Provides the length of longest message that can be recovered + /// \return the length of longest message that can be recovered, in bytes + /// \details MaxRecoverableLength() returns the length of longest message that can be recovered, or 0 if + /// this signature scheme does not support message recovery. virtual size_t MaxRecoverableLength() const =0; - //! \brief Provides the length of longest message that can be recovered from a signature of given length - //! \param signatureLength the length of the signature, in bytes - //! \return the length of longest message that can be recovered from a signature of given length, in bytes - //! \details MaxRecoverableLengthFromSignatureLength() returns the length of longest message that can be - //! recovered from a signature of given length, or 0 if this signature scheme does not support message - //! recovery. + /// \brief Provides the length of longest message that can be recovered from a signature of given length + /// \param signatureLength the length of the signature, in bytes + /// \return the length of longest message that can be recovered from a signature of given length, in bytes + /// \details MaxRecoverableLengthFromSignatureLength() returns the length of longest message that can be + /// recovered from a signature of given length, or 0 if this signature scheme does not support message + /// recovery. virtual size_t MaxRecoverableLengthFromSignatureLength(size_t signatureLength) const =0; - //! \brief Determines whether a signature scheme requires a random number generator - //! \return true if the signature scheme requires a RandomNumberGenerator() to sign - //! \details if IsProbabilistic() returns false, then NullRNG() can be passed to functions that take - //! RandomNumberGenerator(). + /// \brief Determines whether a signature scheme requires a random number generator + /// \return true if the signature scheme requires a RandomNumberGenerator() to sign + /// \details if IsProbabilistic() returns false, then NullRNG() can be passed to functions that take + /// RandomNumberGenerator(). virtual bool IsProbabilistic() const =0; - //! \brief Determines whether the non-recoverable message part can be signed - //! \return true if the non-recoverable message part can be signed + /// \brief Determines whether the non-recoverable message part can be signed + /// \return true if the non-recoverable message part can be signed virtual bool AllowNonrecoverablePart() const =0; - //! \brief Determines whether the signature must be input before the message - //! \return true if the signature must be input before the message during verifcation - //! \details if SignatureUpfront() returns true, then you must input the signature before the message - //! during verification. Otherwise you can input the signature at anytime. + /// \brief Determines whether the signature must be input before the message + /// \return true if the signature must be input before the message during verifcation + /// \details if SignatureUpfront() returns true, then you must input the signature before the message + /// during verification. Otherwise you can input the signature at anytime. virtual bool SignatureUpfront() const {return false;} - //! \brief Determines whether the recoverable part must be input before the non-recoverable part - //! \return true if the recoverable part must be input before the non-recoverable part during signing - //! \details RecoverablePartFirst() determines whether you must input the recoverable part before the - //! non-recoverable part during signing + /// \brief Determines whether the recoverable part must be input before the non-recoverable part + /// \return true if the recoverable part must be input before the non-recoverable part during signing + /// \details RecoverablePartFirst() determines whether you must input the recoverable part before the + /// non-recoverable part during signing virtual bool RecoverablePartFirst() const =0; }; -//! \class PK_MessageAccumulator -//! \brief Interface for accumulating messages to be signed or verified -//! \details Only Update() should be called from the PK_MessageAccumulator() class. No other functions -//! inherited from HashTransformation, like DigestSize() and TruncatedFinal(), should be called. +/// \class PK_MessageAccumulator +/// \brief Interface for accumulating messages to be signed or verified +/// \details Only Update() should be called from the PK_MessageAccumulator() class. No other functions +/// inherited from HashTransformation, like DigestSize() and TruncatedFinal(), should be called. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_MessageAccumulator : public HashTransformation { public: - //! \warning DigestSize() should not be called on PK_MessageAccumulator + /// \warning DigestSize() should not be called on PK_MessageAccumulator unsigned int DigestSize() const {throw NotImplemented("PK_MessageAccumulator: DigestSize() should not be called");} - //! \warning TruncatedFinal() should not be called on PK_MessageAccumulator + /// \warning TruncatedFinal() should not be called on PK_MessageAccumulator void TruncatedFinal(byte *digest, size_t digestSize) { CRYPTOPP_UNUSED(digest); CRYPTOPP_UNUSED(digestSize); @@ -2636,286 +2636,286 @@ public: } }; -//! \class PK_Signer -//! \brief Interface for public-key signers +/// \class PK_Signer +/// \brief Interface for public-key signers class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Signer : public PK_SignatureScheme, public PrivateKeyAlgorithm { public: virtual ~PK_Signer() {} - //! \brief Create a new HashTransformation to accumulate the message to be signed - //! \param rng a RandomNumberGenerator derived class - //! \return a pointer to a PK_MessageAccumulator - //! \details NewSignatureAccumulator() can be used with all signing methods. Sign() will autimatically delete the - //! accumulator pointer. The caller is responsible for deletion if a method is called that takes a reference. + /// \brief Create a new HashTransformation to accumulate the message to be signed + /// \param rng a RandomNumberGenerator derived class + /// \return a pointer to a PK_MessageAccumulator + /// \details NewSignatureAccumulator() can be used with all signing methods. Sign() will autimatically delete the + /// accumulator pointer. The caller is responsible for deletion if a method is called that takes a reference. virtual PK_MessageAccumulator * NewSignatureAccumulator(RandomNumberGenerator &rng) const =0; - //! \brief Input a recoverable message to an accumulator - //! \param messageAccumulator a reference to a PK_MessageAccumulator - //! \param recoverableMessage a pointer to the recoverable message part to be signed - //! \param recoverableMessageLength the size of the recoverable message part + /// \brief Input a recoverable message to an accumulator + /// \param messageAccumulator a reference to a PK_MessageAccumulator + /// \param recoverableMessage a pointer to the recoverable message part to be signed + /// \param recoverableMessageLength the size of the recoverable message part virtual void InputRecoverableMessage(PK_MessageAccumulator &messageAccumulator, const byte *recoverableMessage, size_t recoverableMessageLength) const =0; - //! \brief Sign and delete the messageAccumulator - //! \param rng a RandomNumberGenerator derived class - //! \param messageAccumulator a pointer to a PK_MessageAccumulator derived class - //! \param signature a block of bytes for the signature - //! \return actual signature length - //! \details Sign() deletes the messageAccumulator, even if an exception is thrown. - //! \pre COUNTOF(signature) == MaxSignatureLength() + /// \brief Sign and delete the messageAccumulator + /// \param rng a RandomNumberGenerator derived class + /// \param messageAccumulator a pointer to a PK_MessageAccumulator derived class + /// \param signature a block of bytes for the signature + /// \return actual signature length + /// \details Sign() deletes the messageAccumulator, even if an exception is thrown. + /// \pre COUNTOF(signature) == MaxSignatureLength() virtual size_t Sign(RandomNumberGenerator &rng, PK_MessageAccumulator *messageAccumulator, byte *signature) const; - //! \brief Sign and restart messageAccumulator - //! \param rng a RandomNumberGenerator derived class - //! \param messageAccumulator a pointer to a PK_MessageAccumulator derived class - //! \param signature a block of bytes for the signature - //! \param restart flag indicating whether the messageAccumulator should be restarted - //! \return actual signature length - //! \pre COUNTOF(signature) == MaxSignatureLength() + /// \brief Sign and restart messageAccumulator + /// \param rng a RandomNumberGenerator derived class + /// \param messageAccumulator a pointer to a PK_MessageAccumulator derived class + /// \param signature a block of bytes for the signature + /// \param restart flag indicating whether the messageAccumulator should be restarted + /// \return actual signature length + /// \pre COUNTOF(signature) == MaxSignatureLength() virtual size_t SignAndRestart(RandomNumberGenerator &rng, PK_MessageAccumulator &messageAccumulator, byte *signature, bool restart=true) const =0; - //! \brief Sign a message - //! \param rng a RandomNumberGenerator derived class - //! \param message a pointer to the message - //! \param messageLen the size of the message to be signed - //! \param signature a block of bytes for the signature - //! \return actual signature length - //! \pre COUNTOF(signature) == MaxSignatureLength() + /// \brief Sign a message + /// \param rng a RandomNumberGenerator derived class + /// \param message a pointer to the message + /// \param messageLen the size of the message to be signed + /// \param signature a block of bytes for the signature + /// \return actual signature length + /// \pre COUNTOF(signature) == MaxSignatureLength() virtual size_t SignMessage(RandomNumberGenerator &rng, const byte *message, size_t messageLen, byte *signature) const; - //! \brief Sign a recoverable message - //! \param rng a RandomNumberGenerator derived class - //! \param recoverableMessage a pointer to the recoverable message part to be signed - //! \param recoverableMessageLength the size of the recoverable message part - //! \param nonrecoverableMessage a pointer to the non-recoverable message part to be signed - //! \param nonrecoverableMessageLength the size of the non-recoverable message part - //! \param signature a block of bytes for the signature - //! \return actual signature length - //! \pre COUNTOF(signature) == MaxSignatureLength(recoverableMessageLength) + /// \brief Sign a recoverable message + /// \param rng a RandomNumberGenerator derived class + /// \param recoverableMessage a pointer to the recoverable message part to be signed + /// \param recoverableMessageLength the size of the recoverable message part + /// \param nonrecoverableMessage a pointer to the non-recoverable message part to be signed + /// \param nonrecoverableMessageLength the size of the non-recoverable message part + /// \param signature a block of bytes for the signature + /// \return actual signature length + /// \pre COUNTOF(signature) == MaxSignatureLength(recoverableMessageLength) virtual size_t SignMessageWithRecovery(RandomNumberGenerator &rng, const byte *recoverableMessage, size_t recoverableMessageLength, const byte *nonrecoverableMessage, size_t nonrecoverableMessageLength, byte *signature) const; }; -//! \class PK_Verifier -//! \brief Interface for public-key signature verifiers -//! \details The Recover* functions throw NotImplemented if the signature scheme does not support -//! message recovery. -//! \details The Verify* functions throw InvalidDataFormat if the scheme does support message -//! recovery and the signature contains a non-empty recoverable message part. The -//! Recover* functions should be used in that case. +/// \class PK_Verifier +/// \brief Interface for public-key signature verifiers +/// \details The Recover* functions throw NotImplemented if the signature scheme does not support +/// message recovery. +/// \details The Verify* functions throw InvalidDataFormat if the scheme does support message +/// recovery and the signature contains a non-empty recoverable message part. The +/// Recover* functions should be used in that case. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Verifier : public PK_SignatureScheme, public PublicKeyAlgorithm { public: virtual ~PK_Verifier() {} - //! \brief Create a new HashTransformation to accumulate the message to be verified - //! \return a pointer to a PK_MessageAccumulator - //! \details NewVerificationAccumulator() can be used with all verification methods. Verify() will autimatically delete - //! the accumulator pointer. The caller is responsible for deletion if a method is called that takes a reference. + /// \brief Create a new HashTransformation to accumulate the message to be verified + /// \return a pointer to a PK_MessageAccumulator + /// \details NewVerificationAccumulator() can be used with all verification methods. Verify() will autimatically delete + /// the accumulator pointer. The caller is responsible for deletion if a method is called that takes a reference. virtual PK_MessageAccumulator * NewVerificationAccumulator() const =0; - //! \brief Input signature into a message accumulator - //! \param messageAccumulator a pointer to a PK_MessageAccumulator derived class - //! \param signature the signature on the message - //! \param signatureLength the size of the signature + /// \brief Input signature into a message accumulator + /// \param messageAccumulator a pointer to a PK_MessageAccumulator derived class + /// \param signature the signature on the message + /// \param signatureLength the size of the signature virtual void InputSignature(PK_MessageAccumulator &messageAccumulator, const byte *signature, size_t signatureLength) const =0; - //! \brief Check whether messageAccumulator contains a valid signature and message - //! \param messageAccumulator a pointer to a PK_MessageAccumulator derived class - //! \return true if the signature is valid, false otherwise - //! \details Verify() deletes the messageAccumulator, even if an exception is thrown. + /// \brief Check whether messageAccumulator contains a valid signature and message + /// \param messageAccumulator a pointer to a PK_MessageAccumulator derived class + /// \return true if the signature is valid, false otherwise + /// \details Verify() deletes the messageAccumulator, even if an exception is thrown. virtual bool Verify(PK_MessageAccumulator *messageAccumulator) const; - //! \brief Check whether messageAccumulator contains a valid signature and message, and restart messageAccumulator - //! \param messageAccumulator a reference to a PK_MessageAccumulator derived class - //! \return true if the signature is valid, false otherwise - //! \details VerifyAndRestart() restarts the messageAccumulator + /// \brief Check whether messageAccumulator contains a valid signature and message, and restart messageAccumulator + /// \param messageAccumulator a reference to a PK_MessageAccumulator derived class + /// \return true if the signature is valid, false otherwise + /// \details VerifyAndRestart() restarts the messageAccumulator virtual bool VerifyAndRestart(PK_MessageAccumulator &messageAccumulator) const =0; - //! \brief Check whether input signature is a valid signature for input message - //! \param message a pointer to the message to be verified - //! \param messageLen the size of the message - //! \param signature a pointer to the signature over the message - //! \param signatureLen the size of the signature - //! \return true if the signature is valid, false otherwise + /// \brief Check whether input signature is a valid signature for input message + /// \param message a pointer to the message to be verified + /// \param messageLen the size of the message + /// \param signature a pointer to the signature over the message + /// \param signatureLen the size of the signature + /// \return true if the signature is valid, false otherwise virtual bool VerifyMessage(const byte *message, size_t messageLen, const byte *signature, size_t signatureLen) const; - //! \brief Recover a message from its signature - //! \param recoveredMessage a pointer to the recoverable message part to be verified - //! \param messageAccumulator a pointer to a PK_MessageAccumulator derived class - //! \return the result of the verification operation - //! \details Recover() deletes the messageAccumulator, even if an exception is thrown. - //! \pre COUNTOF(recoveredMessage) == MaxRecoverableLengthFromSignatureLength(signatureLength) + /// \brief Recover a message from its signature + /// \param recoveredMessage a pointer to the recoverable message part to be verified + /// \param messageAccumulator a pointer to a PK_MessageAccumulator derived class + /// \return the result of the verification operation + /// \details Recover() deletes the messageAccumulator, even if an exception is thrown. + /// \pre COUNTOF(recoveredMessage) == MaxRecoverableLengthFromSignatureLength(signatureLength) virtual DecodingResult Recover(byte *recoveredMessage, PK_MessageAccumulator *messageAccumulator) const; - //! \brief Recover a message from its signature - //! \param recoveredMessage a pointer to the recoverable message part to be verified - //! \param messageAccumulator a pointer to a PK_MessageAccumulator derived class - //! \return the result of the verification operation - //! \details RecoverAndRestart() restarts the messageAccumulator - //! \pre COUNTOF(recoveredMessage) == MaxRecoverableLengthFromSignatureLength(signatureLength) + /// \brief Recover a message from its signature + /// \param recoveredMessage a pointer to the recoverable message part to be verified + /// \param messageAccumulator a pointer to a PK_MessageAccumulator derived class + /// \return the result of the verification operation + /// \details RecoverAndRestart() restarts the messageAccumulator + /// \pre COUNTOF(recoveredMessage) == MaxRecoverableLengthFromSignatureLength(signatureLength) virtual DecodingResult RecoverAndRestart(byte *recoveredMessage, PK_MessageAccumulator &messageAccumulator) const =0; - //! \brief Recover a message from its signature - //! \param recoveredMessage a pointer for the recovered message - //! \param nonrecoverableMessage a pointer to the non-recoverable message part to be signed - //! \param nonrecoverableMessageLength the size of the non-recoverable message part - //! \param signature the signature on the message - //! \param signatureLength the size of the signature - //! \return the result of the verification operation - //! \pre COUNTOF(recoveredMessage) == MaxRecoverableLengthFromSignatureLength(signatureLength) + /// \brief Recover a message from its signature + /// \param recoveredMessage a pointer for the recovered message + /// \param nonrecoverableMessage a pointer to the non-recoverable message part to be signed + /// \param nonrecoverableMessageLength the size of the non-recoverable message part + /// \param signature the signature on the message + /// \param signatureLength the size of the signature + /// \return the result of the verification operation + /// \pre COUNTOF(recoveredMessage) == MaxRecoverableLengthFromSignatureLength(signatureLength) virtual DecodingResult RecoverMessage(byte *recoveredMessage, const byte *nonrecoverableMessage, size_t nonrecoverableMessageLength, const byte *signature, size_t signatureLength) const; }; -//! \class SimpleKeyAgreementDomain -//! \brief Interface for domains of simple key agreement protocols -//! \details A key agreement 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. +/// \class SimpleKeyAgreementDomain +/// \brief Interface for domains of simple key agreement protocols +/// \details A key agreement 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. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE SimpleKeyAgreementDomain : public KeyAgreementAlgorithm { public: virtual ~SimpleKeyAgreementDomain() {} - //! \brief Provides the size of the agreed value - //! \return size of agreed value produced in this domain + /// \brief Provides the size of the agreed value + /// \return size of agreed value produced in this domain virtual unsigned int AgreedValueLength() const =0; - //! \brief Provides the size of the private key - //! \return size of private keys in this domain + /// \brief Provides the size of the private key + /// \return size of private keys in this domain virtual unsigned int PrivateKeyLength() const =0; - //! \brief Provides the size of the public key - //! \return size of public keys in this domain + /// \brief Provides the size of the public key + /// \return size of public keys in this domain virtual unsigned int PublicKeyLength() const =0; - //! \brief Generate private key in this domain - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer for the generated private key in this domain - //! \pre COUNTOF(privateKey) == PrivateKeyLength() + /// \brief Generate private key in this domain + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer for the generated private key in this domain + /// \pre COUNTOF(privateKey) == PrivateKeyLength() virtual void GeneratePrivateKey(RandomNumberGenerator &rng, byte *privateKey) const =0; - //! \brief Generate a public key from a private key in this domain - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer with the previously generated private key - //! \param publicKey a byte buffer for the generated public key in this domain - //! \pre COUNTOF(publicKey) == PublicKeyLength() + /// \brief Generate a public key from a private key in this domain + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer with the previously generated private key + /// \param publicKey a byte buffer for the generated public key in this domain + /// \pre COUNTOF(publicKey) == PublicKeyLength() virtual void GeneratePublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const =0; - //! \brief Generate a private/public key pair - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer for the generated private key in this domain - //! \param publicKey a byte buffer for the generated public key in this domain - //! \details GenerateKeyPair() is equivalent to calling GeneratePrivateKey() and then GeneratePublicKey(). - //! \pre COUNTOF(privateKey) == PrivateKeyLength() - //! \pre COUNTOF(publicKey) == PublicKeyLength() + /// \brief Generate a private/public key pair + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer for the generated private key in this domain + /// \param publicKey a byte buffer for the generated public key in this domain + /// \details GenerateKeyPair() is equivalent to calling GeneratePrivateKey() and then GeneratePublicKey(). + /// \pre COUNTOF(privateKey) == PrivateKeyLength() + /// \pre COUNTOF(publicKey) == PublicKeyLength() virtual void GenerateKeyPair(RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const; - //! \brief Derive agreed value - //! \param agreedValue a byte buffer for the shared secret - //! \param privateKey a byte buffer with your private key in this domain - //! \param otherPublicKey a byte buffer with the other party's public key in this domain - //! \param validateOtherPublicKey a flag indicating if the other party's public key should be validated - //! \return true upon success, false in case of failure - //! \details Agree() derives an agreed value from your private keys and couterparty's public keys. - //! \details The other party's public key is validated by default. If you have previously validated the - //! static public key, use validateStaticOtherPublicKey=false to save time. - //! \pre COUNTOF(agreedValue) == AgreedValueLength() - //! \pre COUNTOF(privateKey) == PrivateKeyLength() - //! \pre COUNTOF(otherPublicKey) == PublicKeyLength() + /// \brief Derive agreed value + /// \param agreedValue a byte buffer for the shared secret + /// \param privateKey a byte buffer with your private key in this domain + /// \param otherPublicKey a byte buffer with the other party's public key in this domain + /// \param validateOtherPublicKey a flag indicating if the other party's public key should be validated + /// \return true upon success, false in case of failure + /// \details Agree() derives an agreed value from your private keys and couterparty's public keys. + /// \details The other party's public key is validated by default. If you have previously validated the + /// static public key, use validateStaticOtherPublicKey=false to save time. + /// \pre COUNTOF(agreedValue) == AgreedValueLength() + /// \pre COUNTOF(privateKey) == PrivateKeyLength() + /// \pre COUNTOF(otherPublicKey) == PublicKeyLength() virtual bool Agree(byte *agreedValue, const byte *privateKey, const byte *otherPublicKey, bool validateOtherPublicKey=true) const =0; }; -//! \brief Interface for domains of authenticated key agreement protocols -//! \details In an authenticated key agreement protocol, each party has two -//! key pairs. The long-lived key pair is called the static key pair, -//! and the short-lived key pair is called the ephemeral key pair. +/// \brief Interface for domains of authenticated key agreement protocols +/// \details In an authenticated key agreement protocol, each party has two +/// key pairs. The long-lived key pair is called the static key pair, +/// and the short-lived key pair is called the ephemeral key pair. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AuthenticatedKeyAgreementDomain : public KeyAgreementAlgorithm { public: virtual ~AuthenticatedKeyAgreementDomain() {} - //! \brief Provides the size of the agreed value - //! \return size of agreed value produced in this domain + /// \brief Provides the size of the agreed value + /// \return size of agreed value produced in this domain virtual unsigned int AgreedValueLength() const =0; - //! \brief Provides the size of the static private key - //! \return size of static private keys in this domain + /// \brief Provides the size of the static private key + /// \return size of static private keys in this domain virtual unsigned int StaticPrivateKeyLength() const =0; - //! \brief Provides the size of the static public key - //! \return size of static public keys in this domain + /// \brief Provides the size of the static public key + /// \return size of static public keys in this domain virtual unsigned int StaticPublicKeyLength() const =0; - //! \brief Generate static private key in this domain - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer for the generated private key in this domain - //! \pre COUNTOF(privateKey) == PrivateStaticKeyLength() + /// \brief Generate static private key in this domain + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer for the generated private key in this domain + /// \pre COUNTOF(privateKey) == PrivateStaticKeyLength() virtual void GenerateStaticPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const =0; - //! \brief Generate a static public key from a private key in this domain - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer with the previously generated private key - //! \param publicKey a byte buffer for the generated public key in this domain - //! \pre COUNTOF(publicKey) == PublicStaticKeyLength() + /// \brief Generate a static public key from a private key in this domain + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer with the previously generated private key + /// \param publicKey a byte buffer for the generated public key in this domain + /// \pre COUNTOF(publicKey) == PublicStaticKeyLength() virtual void GenerateStaticPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const =0; - //! \brief Generate a static private/public key pair - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer for the generated private key in this domain - //! \param publicKey a byte buffer for the generated public key in this domain - //! \details GenerateStaticKeyPair() is equivalent to calling GenerateStaticPrivateKey() and then GenerateStaticPublicKey(). - //! \pre COUNTOF(privateKey) == PrivateStaticKeyLength() - //! \pre COUNTOF(publicKey) == PublicStaticKeyLength() + /// \brief Generate a static private/public key pair + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer for the generated private key in this domain + /// \param publicKey a byte buffer for the generated public key in this domain + /// \details GenerateStaticKeyPair() is equivalent to calling GenerateStaticPrivateKey() and then GenerateStaticPublicKey(). + /// \pre COUNTOF(privateKey) == PrivateStaticKeyLength() + /// \pre COUNTOF(publicKey) == PublicStaticKeyLength() virtual void GenerateStaticKeyPair(RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const; - //! \brief Provides the size of ephemeral private key - //! \return the size of ephemeral private key in this domain + /// \brief Provides the size of ephemeral private key + /// \return the size of ephemeral private key in this domain virtual unsigned int EphemeralPrivateKeyLength() const =0; - //! \brief Provides the size of ephemeral public key - //! \return the size of ephemeral public key in this domain + /// \brief Provides the size of ephemeral public key + /// \return the size of ephemeral public key in this domain virtual unsigned int EphemeralPublicKeyLength() const =0; - //! \brief Generate ephemeral private key - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer for the generated private key in this domain - //! \pre COUNTOF(privateKey) == PrivateEphemeralKeyLength() + /// \brief Generate ephemeral private key + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer for the generated private key in this domain + /// \pre COUNTOF(privateKey) == PrivateEphemeralKeyLength() virtual void GenerateEphemeralPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const =0; - //! \brief Generate ephemeral public key - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer for the generated private key in this domain - //! \param publicKey a byte buffer for the generated public key in this domain - //! \pre COUNTOF(publicKey) == PublicEphemeralKeyLength() + /// \brief Generate ephemeral public key + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer for the generated private key in this domain + /// \param publicKey a byte buffer for the generated public key in this domain + /// \pre COUNTOF(publicKey) == PublicEphemeralKeyLength() virtual void GenerateEphemeralPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const =0; - //! \brief Generate private/public key pair - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer for the generated private key in this domain - //! \param publicKey a byte buffer for the generated public key in this domain - //! \details GenerateEphemeralKeyPair() is equivalent to calling GenerateEphemeralPrivateKey() and then GenerateEphemeralPublicKey() + /// \brief Generate private/public key pair + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer for the generated private key in this domain + /// \param publicKey a byte buffer for the generated public key in this domain + /// \details GenerateEphemeralKeyPair() is equivalent to calling GenerateEphemeralPrivateKey() and then GenerateEphemeralPublicKey() virtual void GenerateEphemeralKeyPair(RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const; - //! \brief Derive agreed value - //! \param agreedValue a byte buffer for the shared secret - //! \param staticPrivateKey a byte buffer with your static private key in this domain - //! \param ephemeralPrivateKey a byte buffer with your ephemeral private key in this domain - //! \param staticOtherPublicKey a byte buffer with the other party's static public key in this domain - //! \param ephemeralOtherPublicKey a byte buffer with the other party's ephemeral public key in this domain - //! \param validateStaticOtherPublicKey a flag indicating if the other party's public key should be validated - //! \return true upon success, false in case of failure - //! \details Agree() derives an agreed value from your private keys and couterparty's public keys. - //! \details The other party's ephemeral public key is validated by default. If you have previously validated - //! the static public key, use validateStaticOtherPublicKey=false to save time. - //! \pre COUNTOF(agreedValue) == AgreedValueLength() - //! \pre COUNTOF(staticPrivateKey) == StaticPrivateKeyLength() - //! \pre COUNTOF(ephemeralPrivateKey) == EphemeralPrivateKeyLength() - //! \pre COUNTOF(staticOtherPublicKey) == StaticPublicKeyLength() - //! \pre COUNTOF(ephemeralOtherPublicKey) == EphemeralPublicKeyLength() + /// \brief Derive agreed value + /// \param agreedValue a byte buffer for the shared secret + /// \param staticPrivateKey a byte buffer with your static private key in this domain + /// \param ephemeralPrivateKey a byte buffer with your ephemeral private key in this domain + /// \param staticOtherPublicKey a byte buffer with the other party's static public key in this domain + /// \param ephemeralOtherPublicKey a byte buffer with the other party's ephemeral public key in this domain + /// \param validateStaticOtherPublicKey a flag indicating if the other party's public key should be validated + /// \return true upon success, false in case of failure + /// \details Agree() derives an agreed value from your private keys and couterparty's public keys. + /// \details The other party's ephemeral public key is validated by default. If you have previously validated + /// the static public key, use validateStaticOtherPublicKey=false to save time. + /// \pre COUNTOF(agreedValue) == AgreedValueLength() + /// \pre COUNTOF(staticPrivateKey) == StaticPrivateKeyLength() + /// \pre COUNTOF(ephemeralPrivateKey) == EphemeralPrivateKeyLength() + /// \pre COUNTOF(staticOtherPublicKey) == StaticPublicKeyLength() + /// \pre COUNTOF(ephemeralOtherPublicKey) == EphemeralPublicKeyLength() virtual bool Agree(byte *agreedValue, const byte *staticPrivateKey, const byte *ephemeralPrivateKey, const byte *staticOtherPublicKey, const byte *ephemeralOtherPublicKey, @@ -2924,7 +2924,7 @@ public: // interface for password authenticated key agreement protocols, not implemented yet #if 0 -//! \brief Interface for protocol sessions +/// \brief Interface for protocol sessions /*! The methods should be called in the following order: InitializeSession(rng, parameters); // or call initialize method in derived class @@ -2948,14 +2948,14 @@ public: class ProtocolSession { public: - //! Exception thrown when an invalid protocol message is processed + /// Exception thrown when an invalid protocol message is processed class ProtocolError : public Exception { public: ProtocolError(ErrorType errorType, const std::string &s) : Exception(errorType, s) {} }; - //! Exception thrown when a function is called unexpectedly + /// Exception thrown when a function is called unexpectedly /*! for example calling ProcessIncomingMessage() when ProcessedLastMessage() == true */ class UnexpectedMethodCall : public Exception { @@ -3017,7 +3017,7 @@ class PasswordAuthenticatedKeyAgreementDomain : public KeyAgreementAlgorithm public: virtual ~PasswordAuthenticatedKeyAgreementDomain() {} - //! return whether the domain parameters stored in this object are valid + /// return whether the domain parameters stored in this object are valid virtual bool ValidateDomainParameters(RandomNumberGenerator &rng) const {return GetCryptoParameters().Validate(rng, 2);} @@ -3031,7 +3031,7 @@ public: }; #endif -//! \brief Exception thrown when an ASN.1 BER decoing error is encountered +/// \brief Exception thrown when an ASN.1 BER decoing error is encountered class CRYPTOPP_DLL BERDecodeErr : public InvalidArgument { public: @@ -3039,95 +3039,95 @@ public: BERDecodeErr(const std::string &s) : InvalidArgument(s) {} }; -//! \brief Interface for encoding and decoding ASN1 objects -//! \details Each class that derives from ASN1Object should provide a serialization format -//! that controls subobject layout. Most of the time the serialization format is -//! taken from a standard, like P1363 or an RFC. +/// \brief Interface for encoding and decoding ASN1 objects +/// \details Each class that derives from ASN1Object should provide a serialization format +/// that controls subobject layout. Most of the time the serialization format is +/// taken from a standard, like P1363 or an RFC. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE ASN1Object { public: virtual ~ASN1Object() {} - //! \brief Decode this object from a BufferedTransformation - //! \param bt BufferedTransformation object - //! \details Uses Basic Encoding Rules (BER) + /// \brief Decode this object from a BufferedTransformation + /// \param bt BufferedTransformation object + /// \details Uses Basic Encoding Rules (BER) virtual void BERDecode(BufferedTransformation &bt) =0; - //! \brief Encode this object into a BufferedTransformation - //! \param bt BufferedTransformation object - //! \details Uses Distinguished Encoding Rules (DER) + /// \brief Encode this object into a BufferedTransformation + /// \param bt BufferedTransformation object + /// \details Uses Distinguished Encoding Rules (DER) virtual void DEREncode(BufferedTransformation &bt) const =0; - //! \brief Encode this object into a BufferedTransformation - //! \param bt BufferedTransformation object - //! \details Uses Basic Encoding Rules (BER). - //! \details This may be useful if DEREncode() would be too inefficient. + /// \brief Encode this object into a BufferedTransformation + /// \param bt BufferedTransformation object + /// \details Uses Basic Encoding Rules (BER). + /// \details This may be useful if DEREncode() would be too inefficient. virtual void BEREncode(BufferedTransformation &bt) const {DEREncode(bt);} }; -//! \brief Specifies the build-time version of the library -//! \returns integer representing the build-time version -//! \details LibraryVersion can help detect inadvertent mixing and matching of library -//! versions. When using Crypto++ distributed by a third party, LibraryVersion() -//! records the version of the shared object that was built by the third party. -//! The LibraryVersion() record resides in cryptlib.o on Unix compatibles -//! and cryptlib.obj on Windows. It does not change when an app links -//! to the library. -//! \details LibraryVersion() is declared with C linkage (extern "C") within the -//! CryptoPP namespace to help programs locate the symbol. If the symbol is present, then -//! the library version is 5.7 or above. If it is missing, then the library version is -//! 5.6.5 or below. -//! \details The function could be used as shown below. -//! 
-//!     if (LibraryVersion() != HeaderVersion())
-//!     {
-//!         cout << "Potential version mismatch" << endl;
-//!
-//!         const int lmaj = (LibraryVersion() / 100U) % 10;
-//!         const int lmin = (LibraryVersion() / 10U) % 10;
-//!         const int hmaj = (HeaderVersion() / 100U) % 10;
-//!         const int hmin = (HeaderVersion() / 10U) % 10;
-//!
-//!         if(lmaj != hmaj)
-//!             cout << "Major version mismatch" << endl;
-//!         else if(lmin != hmin)
-//!             cout << "Minor version mismatch" << endl;
-//!      }
-//!
-//! \sa HeaderVersion(), GitHub Issue 371. -//! \since Crypto++ 6.0 +/// \brief Specifies the build-time version of the library +/// \returns integer representing the build-time version +/// \details LibraryVersion can help detect inadvertent mixing and matching of library +/// versions. When using Crypto++ distributed by a third party, LibraryVersion() +/// records the version of the shared object that was built by the third party. +/// The LibraryVersion() record resides in cryptlib.o on Unix compatibles +/// and cryptlib.obj on Windows. It does not change when an app links +/// to the library. +/// \details LibraryVersion() is declared with C linkage (extern "C") within the +/// CryptoPP namespace to help programs locate the symbol. If the symbol is present, then +/// the library version is 5.7 or above. If it is missing, then the library version is +/// 5.6.5 or below. +/// \details The function could be used as shown below. +/// 
+///     if (LibraryVersion() != HeaderVersion())
+///     {
+///         cout << "Potential version mismatch" << endl;
+///
+///         const int lmaj = (LibraryVersion() / 100U) % 10;
+///         const int lmin = (LibraryVersion() / 10U) % 10;
+///         const int hmaj = (HeaderVersion() / 100U) % 10;
+///         const int hmin = (HeaderVersion() / 10U) % 10;
+///
+///         if(lmaj != hmaj)
+///             cout << "Major version mismatch" << endl;
+///         else if(lmin != hmin)
+///             cout << "Minor version mismatch" << endl;
+///      }
+///
+/// \sa HeaderVersion(), GitHub Issue 371. +/// \since Crypto++ 6.0 extern "C" { int LibraryVersion(CRYPTOPP_NOINLINE_DOTDOTDOT); } // C linkage -//! \brief Specifies the runtime version of the library -//! \returns integer representing the runtime version -//! \details HeaderVersion() can help detect inadvertent mixing and matching of library -//! versions. When using Crypto++ distributed by a third party, HeaderVersion() -//! records the version of the headers used by the app when the app is compiled. -//! \details HeaderVersion() is declared with C linkage (extern "C") within the -//! CryptoPP namespace to help programs locate the symbol. If the symbol is present, then -//! the library version is 5.7 or above. If it is missing, then the library version is -//! 5.6.5 or below. -//! \details The function could be used as shown below. -//! 
-//!     if (LibraryVersion() != HeaderVersion())
-//!     {
-//!         cout << "Potential version mismatch" << endl;
-//!
-//!         const int lmaj = (LibraryVersion() / 100U) % 10;
-//!         const int lmin = (LibraryVersion() / 10U) % 10;
-//!         const int hmaj = (HeaderVersion() / 100U) % 10;
-//!         const int hmin = (HeaderVersion() / 10U) % 10;
-//!
-//!         if(lmaj != hmaj)
-//!             cout << "Major version mismatch" << endl;
-//!         else if(lmin != hmin)
-//!             cout << "Minor version mismatch" << endl;
-//!      }
-//!
-//! \sa LibraryVersion(), GitHub Issue 371. -//! \since Crypto++ 6.0 +/// \brief Specifies the runtime version of the library +/// \returns integer representing the runtime version +/// \details HeaderVersion() can help detect inadvertent mixing and matching of library +/// versions. When using Crypto++ distributed by a third party, HeaderVersion() +/// records the version of the headers used by the app when the app is compiled. +/// \details HeaderVersion() is declared with C linkage (extern "C") within the +/// CryptoPP namespace to help programs locate the symbol. If the symbol is present, then +/// the library version is 5.7 or above. If it is missing, then the library version is +/// 5.6.5 or below. +/// \details The function could be used as shown below. +/// 
+///     if (LibraryVersion() != HeaderVersion())
+///     {
+///         cout << "Potential version mismatch" << endl;
+///
+///         const int lmaj = (LibraryVersion() / 100U) % 10;
+///         const int lmin = (LibraryVersion() / 10U) % 10;
+///         const int hmaj = (HeaderVersion() / 100U) % 10;
+///         const int hmin = (HeaderVersion() / 10U) % 10;
+///
+///         if(lmaj != hmaj)
+///             cout << "Major version mismatch" << endl;
+///         else if(lmin != hmin)
+///             cout << "Minor version mismatch" << endl;
+///      }
+///
+/// \sa LibraryVersion(), GitHub Issue 371. +/// \since Crypto++ 6.0 extern "C" { inline int HeaderVersion() { diff --git a/default.h b/default.h index 56f54c98..c6097449 100644 --- a/default.h +++ b/default.h @@ -1,7 +1,7 @@ // default.h - originally written and placed in the public domain by Wei Dai -//! \file default.h -//! \brief Classes for DefaultEncryptor, DefaultDecryptor, DefaultEncryptorWithMAC and DefaultDecryptorWithMAC +/// \file default.h +/// \brief Classes for DefaultEncryptor, DefaultDecryptor, DefaultEncryptorWithMAC and DefaultDecryptorWithMAC #ifndef CRYPTOPP_DEFAULT_H #define CRYPTOPP_DEFAULT_H @@ -16,22 +16,22 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Legacy block cipher for LegacyEncryptor, LegacyDecryptor, LegacyEncryptorWithMAC and LegacyDecryptorWithMAC +/// \brief Legacy block cipher for LegacyEncryptor, LegacyDecryptor, LegacyEncryptorWithMAC and LegacyDecryptorWithMAC typedef DES_EDE2 LegacyBlockCipher; -//! \brief Legacy hash for use with LegacyEncryptorWithMAC and LegacyDecryptorWithMAC +/// \brief Legacy hash for use with LegacyEncryptorWithMAC and LegacyDecryptorWithMAC typedef SHA1 LegacyHashModule; -//! \brief Legacy HMAC for use withLegacyEncryptorWithMAC and LegacyDecryptorWithMAC +/// \brief Legacy HMAC for use withLegacyEncryptorWithMAC and LegacyDecryptorWithMAC typedef HMAC LegacyMAC; -//! \brief Default block cipher for DefaultEncryptor, DefaultDecryptor, DefaultEncryptorWithMAC and DefaultDecryptorWithMAC +/// \brief Default block cipher for DefaultEncryptor, DefaultDecryptor, DefaultEncryptorWithMAC and DefaultDecryptorWithMAC typedef AES DefaultBlockCipher; -//! \brief Default hash for use with DefaultEncryptorWithMAC and DefaultDecryptorWithMAC +/// \brief Default hash for use with DefaultEncryptorWithMAC and DefaultDecryptorWithMAC typedef SHA256 DefaultHashModule; -//! \brief Default HMAC for use withDefaultEncryptorWithMAC and DefaultDecryptorWithMAC +/// \brief Default HMAC for use withDefaultEncryptorWithMAC and DefaultDecryptorWithMAC typedef HMAC DefaultMAC; -//! \class DataDecryptorErr -//! \brief Exception thrown when LegacyDecryptorWithMAC or DefaultDecryptorWithMAC decryption error is encountered +/// \class DataDecryptorErr +/// \brief Exception thrown when LegacyDecryptorWithMAC or DefaultDecryptorWithMAC decryption error is encountered class DataDecryptorErr : public Exception { public: @@ -39,24 +39,24 @@ public: : Exception(DATA_INTEGRITY_CHECK_FAILED, s) {} }; -//! \class KeyBadErr -//! \brief Exception thrown when a bad key is encountered in DefaultDecryptorWithMAC and LegacyDecryptorWithMAC +/// \class KeyBadErr +/// \brief Exception thrown when a bad key is encountered in DefaultDecryptorWithMAC and LegacyDecryptorWithMAC class KeyBadErr : public DataDecryptorErr { public: KeyBadErr() : DataDecryptorErr("DataDecryptor: cannot decrypt message with this passphrase") {} }; -//! \class MACBadErr -//! \brief Exception thrown when an incorrect MAC is encountered in DefaultDecryptorWithMAC and LegacyDecryptorWithMAC +/// \class MACBadErr +/// \brief Exception thrown when an incorrect MAC is encountered in DefaultDecryptorWithMAC and LegacyDecryptorWithMAC class MACBadErr : public DataDecryptorErr { public: MACBadErr() : DataDecryptorErr("DataDecryptorWithMAC: MAC check failed") {} }; -//! \class DataParametersInfo -//! \brief Algorithm information for password-based encryptors and decryptors +/// \class DataParametersInfo +/// \brief Algorithm information for password-based encryptors and decryptors template struct DataParametersInfo { @@ -70,15 +70,15 @@ struct DataParametersInfo typedef DataParametersInfo LegacyParametersInfo; typedef DataParametersInfo DefaultParametersInfo; -//! \class DataEncryptor -//! \brief Password-based Encryptor -//! \tparam BC BlockCipher based class used for encryption -//! \tparam H HashTransformation based class used for mashing -//! \tparam Info Constants used by the algorithms -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. -//! \sa DefaultEncryptor, DefaultDecryptor, LegacyEncryptor, LegacyDecryptor -//! \since Crypto++ 2.0 +/// \class DataEncryptor +/// \brief Password-based Encryptor +/// \tparam BC BlockCipher based class used for encryption +/// \tparam H HashTransformation based class used for mashing +/// \tparam Info Constants used by the algorithms +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. +/// \sa DefaultEncryptor, DefaultDecryptor, LegacyEncryptor, LegacyDecryptor +/// \since Crypto++ 2.0 template class DataEncryptor : public ProxyFilter, public Info { @@ -89,15 +89,15 @@ public: CRYPTOPP_CONSTANT(DIGESTSIZE = Info::DIGESTSIZE) CRYPTOPP_CONSTANT(ITERATIONS = Info::ITERATIONS) - //! \brief Construct a DataEncryptor - //! \param passphrase a C-String password - //! \param attachment a BufferedTransformation to attach to this object + /// \brief Construct a DataEncryptor + /// \param passphrase a C-String password + /// \param attachment a BufferedTransformation to attach to this object DataEncryptor(const char *passphrase, BufferedTransformation *attachment = NULLPTR); - //! \brief Construct a DataEncryptor - //! \param passphrase a byte string password - //! \param passphraseLength the length of the byte string password - //! \param attachment a BufferedTransformation to attach to this object + /// \brief Construct a DataEncryptor + /// \param passphrase a byte string password + /// \param passphraseLength the length of the byte string password + /// \param attachment a BufferedTransformation to attach to this object DataEncryptor(const byte *passphrase, size_t passphraseLength, BufferedTransformation *attachment = NULLPTR); protected: @@ -109,15 +109,15 @@ private: typename CBC_Mode::Encryption m_cipher; }; -//! \class DataDecryptor -//! \brief Password-based Decryptor -//! \tparam BC BlockCipher based class used for encryption -//! \tparam H HashTransformation based class used for mashing -//! \tparam Info Constants used by the algorithms -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. -//! \sa DefaultEncryptor, DefaultDecryptor, LegacyEncryptor, LegacyDecryptor -//! \since Crypto++ 2.0 +/// \class DataDecryptor +/// \brief Password-based Decryptor +/// \tparam BC BlockCipher based class used for encryption +/// \tparam H HashTransformation based class used for mashing +/// \tparam Info Constants used by the algorithms +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. +/// \sa DefaultEncryptor, DefaultDecryptor, LegacyEncryptor, LegacyDecryptor +/// \since Crypto++ 2.0 template class DataDecryptor : public ProxyFilter, public Info { @@ -128,17 +128,17 @@ public: CRYPTOPP_CONSTANT(DIGESTSIZE = Info::DIGESTSIZE) CRYPTOPP_CONSTANT(ITERATIONS = Info::ITERATIONS) - //! \brief Constructs a DataDecryptor - //! \param passphrase a C-String password - //! \param attachment a BufferedTransformation to attach to this object - //! \param throwException a flag specifiying whether an Exception should be thrown on error + /// \brief Constructs a DataDecryptor + /// \param passphrase a C-String password + /// \param attachment a BufferedTransformation to attach to this object + /// \param throwException a flag specifiying whether an Exception should be thrown on error DataDecryptor(const char *passphrase, BufferedTransformation *attachment = NULLPTR, bool throwException=true); - //! \brief Constructs a DataDecryptor - //! \param passphrase a byte string password - //! \param passphraseLength the length of the byte string password - //! \param attachment a BufferedTransformation to attach to this object - //! \param throwException a flag specifiying whether an Exception should be thrown on error + /// \brief Constructs a DataDecryptor + /// \param passphrase a byte string password + /// \param passphraseLength the length of the byte string password + /// \param attachment a BufferedTransformation to attach to this object + /// \param throwException a flag specifiying whether an Exception should be thrown on error DataDecryptor(const byte *passphrase, size_t passphraseLength, BufferedTransformation *attachment = NULLPTR, bool throwException=true); enum State {WAITING_FOR_KEYCHECK, KEY_GOOD, KEY_BAD}; @@ -160,22 +160,22 @@ private: }; -//! \class DataEncryptorWithMAC -//! \brief Password-based encryptor with MAC -//! \tparam BC BlockCipher based class used for encryption -//! \tparam H HashTransformation based class used for mashing -//! \tparam MAC HashTransformation based class used for authentication -//! \tparam Info Constants used by the algorithms -//! \details DataEncryptorWithMAC uses a non-standard mashup function called Mash() to derive key -//! bits from the password. -//! \details The purpose of the function Mash() is to take an arbitrary length input string and -//! *deterministically* produce an arbitrary length output string such that (1) it looks random, -//! (2) no information about the input is deducible from it, and (3) it contains as much entropy -//! as it can hold, or the amount of entropy in the input string, whichever is smaller. -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. -//! \sa DefaultEncryptorWithMAC, DefaultDecryptorWithMAC, LegacyDecryptorWithMAC, LegacyEncryptorWithMAC -//! \since Crypto++ 2.0 +/// \class DataEncryptorWithMAC +/// \brief Password-based encryptor with MAC +/// \tparam BC BlockCipher based class used for encryption +/// \tparam H HashTransformation based class used for mashing +/// \tparam MAC HashTransformation based class used for authentication +/// \tparam Info Constants used by the algorithms +/// \details DataEncryptorWithMAC uses a non-standard mashup function called Mash() to derive key +/// bits from the password. +/// \details The purpose of the function Mash() is to take an arbitrary length input string and +/// *deterministically* produce an arbitrary length output string such that (1) it looks random, +/// (2) no information about the input is deducible from it, and (3) it contains as much entropy +/// as it can hold, or the amount of entropy in the input string, whichever is smaller. +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. +/// \sa DefaultEncryptorWithMAC, DefaultDecryptorWithMAC, LegacyDecryptorWithMAC, LegacyEncryptorWithMAC +/// \since Crypto++ 2.0 template class DataEncryptorWithMAC : public ProxyFilter { @@ -186,15 +186,15 @@ public: CRYPTOPP_CONSTANT(DIGESTSIZE = Info::DIGESTSIZE) CRYPTOPP_CONSTANT(ITERATIONS = Info::ITERATIONS) - //! \brief Constructs a DataEncryptorWithMAC - //! \param passphrase a C-String password - //! \param attachment a BufferedTransformation to attach to this object + /// \brief Constructs a DataEncryptorWithMAC + /// \param passphrase a C-String password + /// \param attachment a BufferedTransformation to attach to this object DataEncryptorWithMAC(const char *passphrase, BufferedTransformation *attachment = NULLPTR); - //! \brief Constructs a DataEncryptorWithMAC - //! \param passphrase a byte string password - //! \param passphraseLength the length of the byte string password - //! \param attachment a BufferedTransformation to attach to this object + /// \brief Constructs a DataEncryptorWithMAC + /// \param passphrase a byte string password + /// \param passphraseLength the length of the byte string password + /// \param attachment a BufferedTransformation to attach to this object DataEncryptorWithMAC(const byte *passphrase, size_t passphraseLength, BufferedTransformation *attachment = NULLPTR); protected: @@ -206,22 +206,22 @@ private: }; -//! \class DataDecryptorWithMAC -//! \brief Password-based decryptor with MAC -//! \tparam BC BlockCipher based class used for encryption -//! \tparam H HashTransformation based class used for mashing -//! \tparam MAC HashTransformation based class used for authentication -//! \tparam Info Constants used by the algorithms -//! \details DataDecryptorWithMAC uses a non-standard mashup function called Mash() to derive key -//! bits from the password. -//! \details The purpose of the function Mash() is to take an arbitrary length input string and -//! *deterministically* produce an arbitrary length output string such that (1) it looks random, -//! (2) no information about the input is deducible from it, and (3) it contains as much entropy -//! as it can hold, or the amount of entropy in the input string, whichever is smaller. -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. -//! \sa DefaultEncryptorWithMAC, DefaultDecryptorWithMAC, LegacyDecryptorWithMAC, LegacyEncryptorWithMAC -//! \since Crypto++ 2.0 +/// \class DataDecryptorWithMAC +/// \brief Password-based decryptor with MAC +/// \tparam BC BlockCipher based class used for encryption +/// \tparam H HashTransformation based class used for mashing +/// \tparam MAC HashTransformation based class used for authentication +/// \tparam Info Constants used by the algorithms +/// \details DataDecryptorWithMAC uses a non-standard mashup function called Mash() to derive key +/// bits from the password. +/// \details The purpose of the function Mash() is to take an arbitrary length input string and +/// *deterministically* produce an arbitrary length output string such that (1) it looks random, +/// (2) no information about the input is deducible from it, and (3) it contains as much entropy +/// as it can hold, or the amount of entropy in the input string, whichever is smaller. +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. +/// \sa DefaultEncryptorWithMAC, DefaultDecryptorWithMAC, LegacyDecryptorWithMAC, LegacyEncryptorWithMAC +/// \since Crypto++ 2.0 template class DataDecryptorWithMAC : public ProxyFilter { @@ -232,17 +232,17 @@ public: CRYPTOPP_CONSTANT(DIGESTSIZE = Info::DIGESTSIZE) CRYPTOPP_CONSTANT(ITERATIONS = Info::ITERATIONS) - //! \brief Constructs a DataDecryptor - //! \param passphrase a C-String password - //! \param attachment a BufferedTransformation to attach to this object - //! \param throwException a flag specifiying whether an Exception should be thrown on error + /// \brief Constructs a DataDecryptor + /// \param passphrase a C-String password + /// \param attachment a BufferedTransformation to attach to this object + /// \param throwException a flag specifiying whether an Exception should be thrown on error DataDecryptorWithMAC(const char *passphrase, BufferedTransformation *attachment = NULLPTR, bool throwException=true); - //! \brief Constructs a DataDecryptor - //! \param passphrase a byte string password - //! \param passphraseLength the length of the byte string password - //! \param attachment a BufferedTransformation to attach to this object - //! \param throwException a flag specifiying whether an Exception should be thrown on error + /// \brief Constructs a DataDecryptor + /// \param passphrase a byte string password + /// \param passphraseLength the length of the byte string password + /// \param attachment a BufferedTransformation to attach to this object + /// \param throwException a flag specifiying whether an Exception should be thrown on error DataDecryptorWithMAC(const byte *passphrase, size_t passphraseLength, BufferedTransformation *attachment = NULLPTR, bool throwException=true); typename DataDecryptor::State CurrentState() const; @@ -259,53 +259,53 @@ private: }; #if defined(CRYPTOPP_DOXYGEN_PROCESSING) -//! \class LegacyEncryptor -//! \brief Password-based encryptor (deprecated) -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the -//! Default* classes, and the old algorithms are available with the Legacy* classes. +/// \class LegacyEncryptor +/// \brief Password-based encryptor (deprecated) +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the +/// Default* classes, and the old algorithms are available with the Legacy* classes. struct LegacyEncryptor : public DataEncryptor {}; -//! \class LegacyDecryptor -//! \brief Password-based decryptor (deprecated) -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the -//! Default* classes, and the old algorithms are available with the Legacy* classes. +/// \class LegacyDecryptor +/// \brief Password-based decryptor (deprecated) +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the +/// Default* classes, and the old algorithms are available with the Legacy* classes. struct LegacyDecryptor : public DataDecryptor {}; -//! \class DefaultEncryptor -//! \brief Password-based encryptor -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the -//! Default* classes, and the old algorithms are available with the Legacy* classes. +/// \class DefaultEncryptor +/// \brief Password-based encryptor +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the +/// Default* classes, and the old algorithms are available with the Legacy* classes. struct DefaultEncryptor : public DataEncryptor {}; -//! \class DefaultDecryptor -//! \brief Password-based decryptor -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the -//! Default* classes, and the old algorithms are available with the Legacy* classes. +/// \class DefaultDecryptor +/// \brief Password-based decryptor +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the +/// Default* classes, and the old algorithms are available with the Legacy* classes. struct DefaultDecryptor : public DataDecryptor {}; -//! \class LegacyEncryptorWithMAC -//! \brief Password-based encryptor with MAC (deprecated) -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the -//! Default* classes, and the old algorithms are available with the Legacy* classes. +/// \class LegacyEncryptorWithMAC +/// \brief Password-based encryptor with MAC (deprecated) +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the +/// Default* classes, and the old algorithms are available with the Legacy* classes. struct LegacyEncryptorWithMAC : public DataEncryptorWithMAC {}; -//! \class LegacyDecryptorWithMAC -//! \brief Password-based decryptor with MAC (deprecated) -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the -//! Default* classes, and the old algorithms are available with the Legacy* classes. +/// \class LegacyDecryptorWithMAC +/// \brief Password-based decryptor with MAC (deprecated) +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the +/// Default* classes, and the old algorithms are available with the Legacy* classes. struct LegacyDecryptorWithMAC : public DataDecryptorWithMAC {}; -//! \class DefaultEncryptorWithMAC -//! \brief Password-based encryptor with MAC -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the -//! Default* classes, and the old algorithms are available with the Legacy* classes. +/// \class DefaultEncryptorWithMAC +/// \brief Password-based encryptor with MAC +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the +/// Default* classes, and the old algorithms are available with the Legacy* classes. struct DefaultEncryptorWithMAC : public DataEncryptorWithMAC {}; -//! \class DefaultDecryptorWithMAC -//! \brief Password-based decryptor with MAC -//! \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. -//! Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the -//! Default* classes, and the old algorithms are available with the Legacy* classes. +/// \class DefaultDecryptorWithMAC +/// \brief Password-based decryptor with MAC +/// \details Crypto++ 5.6.5 and earlier used the legacy algorithms, including DES_EDE2 and SHA1. +/// Crypto++ 5.7 switched to AES and SHA256. The updated algorithms are available with the +/// Default* classes, and the old algorithms are available with the Legacy* classes. struct DefaultDecryptorWithMAC : public DataDecryptorWithMAC {}; #else typedef DataEncryptor LegacyEncryptor; diff --git a/des.h b/des.h index e526ede5..e4171988 100644 --- a/des.h +++ b/des.h @@ -1,7 +1,7 @@ // des.h - originally written and placed in the public domain by Wei Dai -//! \file des.h -//! \brief Classes for DES, 2-key Triple-DES, 3-key Triple-DES and DESX +/// \file des.h +/// \brief Classes for DES, 2-key Triple-DES, 3-key Triple-DES and DESX #ifndef CRYPTOPP_DES_H #define CRYPTOPP_DES_H @@ -11,8 +11,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RawDES -//! \brief DES block cipher base class +/// \class RawDES +/// \brief DES block cipher base class class CRYPTOPP_DLL RawDES { public: @@ -25,25 +25,25 @@ protected: FixedSizeSecBlock k; }; -//! \class DES_Info -//! \brief DES block cipher information +/// \class DES_Info +/// \brief DES block cipher information struct DES_Info : public FixedBlockSize<8>, public FixedKeyLength<8> { // disable DES in DLL version by not exporting this function CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "DES";} }; -//! \class DES -//! \brief DES block cipher -//! \details The DES implementation in Crypto++ ignores the parity bits -//! (the least significant bits of each byte) in the key. However you can use CheckKeyParityBits() -//! and CorrectKeyParityBits() to check or correct the parity bits if you wish. -//! \sa DES -//! \since Crypto++ 1.0 +/// \class DES +/// \brief DES block cipher +/// \details The DES implementation in Crypto++ ignores the parity bits +/// (the least significant bits of each byte) in the key. However you can use CheckKeyParityBits() +/// and CorrectKeyParityBits() to check or correct the parity bits if you wish. +/// \sa DES +/// \since Crypto++ 1.0 class DES : public DES_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief DES block cipher default operation + /// \class Base + /// \brief DES block cipher default operation class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl, public RawDES { public: @@ -52,30 +52,30 @@ class DES : public DES_Info, public BlockCipherDocumentation }; public: - //! check DES key parity bits + /// check DES key parity bits static bool CheckKeyParityBits(const byte *key); - //! correct DES key parity bits + /// correct DES key parity bits static void CorrectKeyParityBits(byte *key); typedef BlockCipherFinal Encryption; typedef BlockCipherFinal Decryption; }; -//! \class DES_EDE2_Info -//! \brief 2-key TripleDES block cipher information +/// \class DES_EDE2_Info +/// \brief 2-key TripleDES block cipher information struct DES_EDE2_Info : public FixedBlockSize<8>, public FixedKeyLength<16> { CRYPTOPP_DLL static const char * CRYPTOPP_API StaticAlgorithmName() {return "DES-EDE2";} }; -//! \class DES_EDE2 -//! \brief 2-key TripleDES block cipher -//! \sa DES-EDE2 -//! \since Crypto++ 1.0 +/// \class DES_EDE2 +/// \brief 2-key TripleDES block cipher +/// \sa DES-EDE2 +/// \since Crypto++ 1.0 class DES_EDE2 : public DES_EDE2_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief DES_EDE2 block cipher default operation + /// \class Base + /// \brief DES_EDE2 block cipher default operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -91,21 +91,21 @@ public: typedef BlockCipherFinal Decryption; }; -//! \class DES_EDE3_Info -//! \brief 3-key TripleDES block cipher information +/// \class DES_EDE3_Info +/// \brief 3-key TripleDES block cipher information struct DES_EDE3_Info : public FixedBlockSize<8>, public FixedKeyLength<24> { CRYPTOPP_DLL static const char * CRYPTOPP_API StaticAlgorithmName() {return "DES-EDE3";} }; -//! \class DES_EDE3 -//! \brief 3-key TripleDES block cipher -//! \sa DES-EDE3 -//! \since Crypto++ 1.0 +/// \class DES_EDE3 +/// \brief 3-key TripleDES block cipher +/// \sa DES-EDE3 +/// \since Crypto++ 1.0 class DES_EDE3 : public DES_EDE3_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief DES_EDE3 block cipher default operation + /// \class Base + /// \brief DES_EDE3 block cipher default operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -121,21 +121,21 @@ public: typedef BlockCipherFinal Decryption; }; -//! \class DES_XEX3_Info -//! \brief DESX block cipher information +/// \class DES_XEX3_Info +/// \brief DESX block cipher information struct DES_XEX3_Info : public FixedBlockSize<8>, public FixedKeyLength<24> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "DES-XEX3";} }; -//! \class DES_XEX3 -//! \brief DESX block cipher -//! \sa DES-XEX3, AKA DESX -//! \since Crypto++ 1.0 +/// \class DES_XEX3 +/// \brief DESX block cipher +/// \sa DES-XEX3, AKA DESX +/// \since Crypto++ 1.0 class DES_XEX3 : public DES_XEX3_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief DES_XEX3 block cipher default operation + /// \class Base + /// \brief DES_XEX3 block cipher default operation class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: diff --git a/dh.h b/dh.h index 3d3dba12..e54cf0ea 100644 --- a/dh.h +++ b/dh.h @@ -1,7 +1,7 @@ // dh.h - originally written and placed in the public domain by Wei Dai -//! \file dh.h -//! \brief Classes for Diffie-Hellman key exchange +/// \file dh.h +/// \brief Classes for Diffie-Hellman key exchange #ifndef CRYPTOPP_DH_H #define CRYPTOPP_DH_H @@ -12,16 +12,16 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class DH_Domain -//! \brief Diffie-Hellman domain -//! \tparam GROUP_PARAMETERS group parameters -//! \tparam COFACTOR_OPTION cofactor multiplication option -//! \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. -//! \details For COFACTOR_OPTION, see CofactorMultiplicationOption. -//! \sa DL_SimpleKeyAgreementDomainBase -//! \since Crypto++ 1.0 +/// \class DH_Domain +/// \brief Diffie-Hellman domain +/// \tparam GROUP_PARAMETERS group parameters +/// \tparam COFACTOR_OPTION cofactor multiplication option +/// \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. +/// \details For COFACTOR_OPTION, see CofactorMultiplicationOption. +/// \sa DL_SimpleKeyAgreementDomainBase +/// \since Crypto++ 1.0 template class DH_Domain : public DL_SimpleKeyAgreementDomainBase { @@ -35,104 +35,104 @@ public: virtual ~DH_Domain() {} - //! \brief Construct a Diffie-Hellman domain + /// \brief Construct a Diffie-Hellman domain DH_Domain() {} - //! \brief Construct a Diffie-Hellman domain - //! \param params group parameters and options + /// \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 + /// \brief Construct a Diffie-Hellman domain + /// \param bt BufferedTransformation with group parameters and options DH_Domain(BufferedTransformation &bt) {m_groupParameters.BERDecode(bt);} - //! \brief Create 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. + /// \brief Create 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 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 - //! \param v2 second parameter - //! \param v3 third parameter - //! \details v1, v2 and v3 are passed directly to the GROUP_PARAMETERS object. + /// \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 + /// \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 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 - //! \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. + /// \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 + /// \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. + /// \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. + /// \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. + /// \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 + /// \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 + /// \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() + /// \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); @@ -169,45 +169,45 @@ private: CRYPTOPP_DLL_TEMPLATE_CLASS DH_Domain; -//! \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 << hex << k1 << endl;
-//!
-//!   cout << "Public key:\n";
-//!   cout << 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 on the Crypto++ wiki and -//! Diffie-Hellman in GF(p) with key validation -//! \since Crypto++ 1.0 +/// \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 << hex << k1 << endl;
+///
+///   cout << "Public key:\n";
+///   cout << 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 on the Crypto++ wiki and +/// Diffie-Hellman in GF(p) with key validation +/// \since Crypto++ 1.0 #if defined(CRYPTOPP_DOXYGEN_PROCESSING) struct DH : public DH_Domain { @@ -216,53 +216,53 @@ struct DH : public DH_Domain virtual ~DH() {} - //! \brief Create an uninitialized Diffie-Hellman object + /// \brief Create an uninitialized Diffie-Hellman object DH() : DH_Domain() {} - //! \brief Initialize a Diffie-Hellman object - //! \param bt BufferedTransformation with group parameters and options + /// \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 + /// \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. + /// \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 p the modulus - //! \param g the generator + /// \brief Initialize a Diffie-Hellman object + /// \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 p the modulus - //! \param q the subgroup order - //! \param g the generator + /// \brief Initialize a Diffie-Hellman object + /// \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. + /// \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 p the modulus - //! \param g the generator + /// \brief Initialize a Diffie-Hellman object + /// \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 p the modulus - //! \param q the subgroup order - //! \param g the generator + /// \brief Initialize a Diffie-Hellman object + /// \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);} }; diff --git a/dh2.h b/dh2.h index 2163de27..4795387b 100644 --- a/dh2.h +++ b/dh2.h @@ -1,7 +1,7 @@ // dh2.h - originally written and placed in the public domain by Wei Dai -//! \file dh2.h -//! \brief Classes for Unified Diffie-Hellman key exchange +/// \file dh2.h +/// \brief Classes for Unified Diffie-Hellman key exchange #ifndef CRYPTOPP_DH2_H #define CRYPTOPP_DH2_H @@ -10,22 +10,22 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class DH2 -//! \brief Unified Diffie-Hellman in GF(p) -//! \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. -//! \sa AuthenticatedKeyAgreementDomain, Unified Diffie-Hellman -//! \since Crypto++ 1.0 +/// \class DH2 +/// \brief Unified Diffie-Hellman in GF(p) +/// \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. +/// \sa AuthenticatedKeyAgreementDomain, Unified Diffie-Hellman +/// \since Crypto++ 1.0 class DH2 : public AuthenticatedKeyAgreementDomain { public: virtual ~DH2() {} - //! \brief Construct a DH2 + /// \brief Construct a DH2 DH2(SimpleKeyAgreementDomain &domain) : d1(domain), d2(domain) {} - //! \brief Construct a DH2 + /// \brief Construct a DH2 DH2(SimpleKeyAgreementDomain &staticDomain, SimpleKeyAgreementDomain &ephemeralDomain) : d1(staticDomain), d2(ephemeralDomain) {} diff --git a/dll.h b/dll.h index a15096e9..bd8acf10 100644 --- a/dll.h +++ b/dll.h @@ -1,8 +1,8 @@ // dll.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile dll.h -//! \brief Functions and definitions required for building the FIPS-140 DLL on Windows +/// \file +/// \headerfile dll.h +/// \brief Functions and definitions required for building the FIPS-140 DLL on Windows #ifndef CRYPTOPP_DLL_H #define CRYPTOPP_DLL_H diff --git a/dmac.h b/dmac.h index 1af7e04a..f7e17ce0 100644 --- a/dmac.h +++ b/dmac.h @@ -1,8 +1,8 @@ // dmac.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile dmac.h -//! \brief Classes for DMAC message authentication code +/// \file +/// \headerfile dmac.h +/// \brief Classes for DMAC message authentication code #ifndef CRYPTOPP_DMAC_H #define CRYPTOPP_DMAC_H @@ -11,9 +11,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class DMAC_Base -//! \brief DMAC message authentication code base class -//! \tparam T class derived from BlockCipherDocumentation +/// \class DMAC_Base +/// \brief DMAC message authentication code base class +/// \tparam T class derived from BlockCipherDocumentation template class CRYPTOPP_NO_VTABLE DMAC_Base : public SameKeyLengthAs, public MessageAuthenticationCode { @@ -39,21 +39,21 @@ private: unsigned int m_counter; }; -//! \class DMAC -//! \brief DMAC message authentication code -//! \tparam T class derived from BlockCipherDocumentation -//! \sa CBC MAC for Real-Time Data Sources (08.15.1997) -//! by Erez Petrank and Charles Rackoff +/// \class DMAC +/// \brief DMAC message authentication code +/// \tparam T class derived from BlockCipherDocumentation +/// \sa CBC MAC for Real-Time Data Sources (08.15.1997) +/// by Erez Petrank and Charles Rackoff template class DMAC : public MessageAuthenticationCodeFinal > { public: - //! \brief Construct a DMAC + /// \brief Construct a DMAC DMAC() {} - //! \brief Construct a DMAC - //! \param key a byte array used to key the cipher - //! \param length the size of the byte array, in bytes + /// \brief Construct a DMAC + /// \param key a byte array used to key the cipher + /// \param length the size of the byte array, in bytes DMAC(const byte *key, size_t length=DMAC_Base::DEFAULT_KEYLENGTH) {this->SetKey(key, length);} }; diff --git a/drbg.h b/drbg.h index 468b8b1c..42b5c788 100644 --- a/drbg.h +++ b/drbg.h @@ -1,10 +1,10 @@ // drbg.h - written and placed in public domain by Jeffrey Walton. -//! \file drbg.h -//! \brief Classes for NIST DRBGs from SP 800-90A -//! \sa Recommendation -//! for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) -//! \since Crypto++ 6.0 +/// \file drbg.h +/// \brief Classes for NIST DRBGs from SP 800-90A +/// \sa Recommendation +/// for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_NIST_DRBG_H #define CRYPTOPP_NIST_DRBG_H @@ -16,16 +16,16 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class NIST_DRBG -//! \brief Interface for NIST DRBGs from SP 800-90A -//! \details NIST_DRBG is the base class interface for NIST DRBGs from SP 800-90A Rev 1 (June 2015) -//! \sa Recommendation -//! for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) -//! \since Crypto++ 6.0 +/// \class NIST_DRBG +/// \brief Interface for NIST DRBGs from SP 800-90A +/// \details NIST_DRBG is the base class interface for NIST DRBGs from SP 800-90A Rev 1 (June 2015) +/// \sa Recommendation +/// for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) +/// \since Crypto++ 6.0 class NIST_DRBG : public RandomNumberGenerator { public: - //! \brief Exception thrown when a NIST DRBG encounters an error + /// \brief Exception thrown when a NIST DRBG encounters an error class Err : public Exception { public: @@ -36,105 +36,105 @@ public: public: virtual ~NIST_DRBG() {} - //! \brief Determines if a generator can accept additional entropy - //! \return true - //! \details All NIST_DRBG return true + /// \brief Determines if a generator can accept additional entropy + /// \return true + /// \details All NIST_DRBG return true virtual bool CanIncorporateEntropy() const {return true;} - //! \brief Update RNG state with additional unpredictable values - //! \param input the entropy to add to the generator - //! \param length the size of the input buffer - //! \throws NIST_DRBG::Err if the generator is reseeded with insufficient entropy - //! \details NIST instantiation and reseed requirements demand the generator is constructed - //! with at least MINIMUM_ENTROPY entropy. The byte array for input must - //! meet NIST SP 800-90B or - //! SP 800-90C requirements. + /// \brief Update RNG state with additional unpredictable values + /// \param input the entropy to add to the generator + /// \param length the size of the input buffer + /// \throws NIST_DRBG::Err if the generator is reseeded with insufficient entropy + /// \details NIST instantiation and reseed requirements demand the generator is constructed + /// with at least MINIMUM_ENTROPY entropy. The byte array for input must + /// meet NIST SP 800-90B or + /// SP 800-90C requirements. virtual void IncorporateEntropy(const byte *input, size_t length)=0; - //! \brief Update RNG state with additional unpredictable values - //! \param entropy the entropy to add to the generator - //! \param entropyLength the size of the input buffer - //! \param additional additional input to add to the generator - //! \param additionaLength the size of the additional input buffer - //! \throws NIST_DRBG::Err if the generator is reseeded with insufficient entropy - //! \details IncorporateEntropy() is an overload provided to match NIST requirements. NIST - //! instantiation and reseed requirements demand the generator is constructed with at least - //! MINIMUM_ENTROPY entropy. The byte array for entropy must meet - //! NIST SP 800-90B or - //!! SP 800-90C requirements. + /// \brief Update RNG state with additional unpredictable values + /// \param entropy the entropy to add to the generator + /// \param entropyLength the size of the input buffer + /// \param additional additional input to add to the generator + /// \param additionaLength the size of the additional input buffer + /// \throws NIST_DRBG::Err if the generator is reseeded with insufficient entropy + /// \details IncorporateEntropy() is an overload provided to match NIST requirements. NIST + /// instantiation and reseed requirements demand the generator is constructed with at least + /// MINIMUM_ENTROPY entropy. The byte array for entropy must meet + /// NIST SP 800-90B or + ///! SP 800-90C requirements. virtual void IncorporateEntropy(const byte *entropy, size_t entropyLength, const byte* additional, size_t additionaLength)=0; - //! \brief Generate random array of bytes - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes - //! \throws NIST_DRBG::Err if a reseed is required - //! \throws NIST_DRBG::Err if the size exceeds MAXIMUM_BYTES_PER_REQUEST + /// \brief Generate random array of bytes + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes + /// \throws NIST_DRBG::Err if a reseed is required + /// \throws NIST_DRBG::Err if the size exceeds MAXIMUM_BYTES_PER_REQUEST virtual void GenerateBlock(byte *output, size_t size)=0; - //! \brief Generate random array of bytes - //! \param additional additional input to add to the generator - //! \param additionaLength the size of the additional input buffer - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes - //! \throws NIST_DRBG::Err if a reseed is required - //! \throws NIST_DRBG::Err if the size exceeds MAXIMUM_BYTES_PER_REQUEST - //! \details GenerateBlock() is an overload provided to match NIST requirements. The byte - //! array for additional input is optional. If present the additional randomness - //! is mixed before generating the output bytes. + /// \brief Generate random array of bytes + /// \param additional additional input to add to the generator + /// \param additionaLength the size of the additional input buffer + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes + /// \throws NIST_DRBG::Err if a reseed is required + /// \throws NIST_DRBG::Err if the size exceeds MAXIMUM_BYTES_PER_REQUEST + /// \details GenerateBlock() is an overload provided to match NIST requirements. The byte + /// array for additional input is optional. If present the additional randomness + /// is mixed before generating the output bytes. virtual void GenerateBlock(const byte* additional, size_t additionaLength, byte *output, size_t size)=0; - //! \brief Provides the security strength - //! \returns The security strength of the generator, in bytes - //! \details The equivalent class constant is SECURITY_STRENGTH + /// \brief Provides the security strength + /// \returns The security strength of the generator, in bytes + /// \details The equivalent class constant is SECURITY_STRENGTH virtual unsigned int SecurityStrength() const=0; - //! \brief Provides the seed length - //! \returns The seed size of the generator, in bytes - //! \details The equivalent class constant is SEED_LENGTH. The size is - //! used to maintain internal state of V and C. + /// \brief Provides the seed length + /// \returns The seed size of the generator, in bytes + /// \details The equivalent class constant is SEED_LENGTH. The size is + /// used to maintain internal state of V and C. virtual unsigned int SeedLength() const=0; - //! \brief Provides the minimum entropy size - //! \returns The minimum entropy size required by the generator, in bytes - //! \details The equivalent class constant is MINIMUM_ENTROPY. All NIST DRBGs must - //! be instaniated with at least MINIMUM_ENTROPY bytes of entropy. The bytes must - //! meet NIST SP 800-90B or - //! SP 800-90C requirements. + /// \brief Provides the minimum entropy size + /// \returns The minimum entropy size required by the generator, in bytes + /// \details The equivalent class constant is MINIMUM_ENTROPY. All NIST DRBGs must + /// be instaniated with at least MINIMUM_ENTROPY bytes of entropy. The bytes must + /// meet NIST SP 800-90B or + /// SP 800-90C requirements. virtual unsigned int MinEntropyLength() const=0; - //! \brief Provides the maximum entropy size - //! \returns The maximum entropy size that can be consumed by the generator, in bytes - //! \details The equivalent class constant is MAXIMUM_ENTROPY. The bytes must - //! meet NIST SP 800-90B or - //! SP 800-90C requirements. MAXIMUM_ENTROPY has been reduced from - //! 235 to INT_MAX to fit the underlying C++ datatype. + /// \brief Provides the maximum entropy size + /// \returns The maximum entropy size that can be consumed by the generator, in bytes + /// \details The equivalent class constant is MAXIMUM_ENTROPY. The bytes must + /// meet NIST SP 800-90B or + /// SP 800-90C requirements. MAXIMUM_ENTROPY has been reduced from + /// 235 to INT_MAX to fit the underlying C++ datatype. virtual unsigned int MaxEntropyLength() const=0; - //! \brief Provides the minimum nonce size - //! \returns The minimum nonce size recommended for the generator, in bytes - //! \details The equivalent class constant is MINIMUM_NONCE. If a nonce is not - //! required then MINIMUM_NONCE is 0. Hash_DRBG does not require a - //! nonce, while HMAC_DRBG and CTR_DRBG require a nonce. + /// \brief Provides the minimum nonce size + /// \returns The minimum nonce size recommended for the generator, in bytes + /// \details The equivalent class constant is MINIMUM_NONCE. If a nonce is not + /// required then MINIMUM_NONCE is 0. Hash_DRBG does not require a + /// nonce, while HMAC_DRBG and CTR_DRBG require a nonce. virtual unsigned int MinNonceLength() const=0; - //! \brief Provides the maximum nonce size - //! \returns The maximum nonce that can be consumed by the generator, in bytes - //! \details The equivalent class constant is MAXIMUM_NONCE. MAXIMUM_NONCE - //! has been reduced from 235 to INT_MAX to fit the underlying C++ datatype. - //! If a nonce is not required then MINIMUM_NONCE is 0. Hash_DRBG does not - //! require a nonce, while HMAC_DRBG and CTR_DRBG require a nonce. + /// \brief Provides the maximum nonce size + /// \returns The maximum nonce that can be consumed by the generator, in bytes + /// \details The equivalent class constant is MAXIMUM_NONCE. MAXIMUM_NONCE + /// has been reduced from 235 to INT_MAX to fit the underlying C++ datatype. + /// If a nonce is not required then MINIMUM_NONCE is 0. Hash_DRBG does not + /// require a nonce, while HMAC_DRBG and CTR_DRBG require a nonce. virtual unsigned int MaxNonceLength() const=0; - //! \brief Provides the maximum size of a request to GenerateBlock - //! \returns The the maximum size of a request to GenerateBlock(), in bytes - //! \details The equivalent class constant is MAXIMUM_BYTES_PER_REQUEST + /// \brief Provides the maximum size of a request to GenerateBlock + /// \returns The the maximum size of a request to GenerateBlock(), in bytes + /// \details The equivalent class constant is MAXIMUM_BYTES_PER_REQUEST virtual unsigned int MaxBytesPerRequest() const=0; - //! \brief Provides the maximum number of requests before a reseed - //! \returns The the maximum number of requests before a reseed, in bytes - //! \details The equivalent class constant is MAXIMUM_REQUESTS_BEFORE_RESEED. - //! MAXIMUM_REQUESTS_BEFORE_RESEED has been reduced from 248 to INT_MAX - //! to fit the underlying C++ datatype. + /// \brief Provides the maximum number of requests before a reseed + /// \returns The the maximum number of requests before a reseed, in bytes + /// \details The equivalent class constant is MAXIMUM_REQUESTS_BEFORE_RESEED. + /// MAXIMUM_REQUESTS_BEFORE_RESEED has been reduced from 248 to INT_MAX + /// to fit the underlying C++ datatype. virtual unsigned int MaxRequestBeforeReseed() const=0; protected: @@ -146,21 +146,21 @@ protected: // ************************************************************* -//! \class Hash_DRBG -//! \tparam HASH NIST approved hash derived from HashTransformation -//! \tparam STRENGTH security strength, in bytes -//! \tparam SEEDLENGTH seed length, in bytes -//! \brief Hash_DRBG from SP 800-90A Rev 1 (June 2015) -//! \details The NIST Hash DRBG is instantiated with a number of parameters. Two of the parameters, -//! Security Strength and Seed Length, depend on the hash and are specified as template parameters. -//! The remaining parameters are included in the class. The parameters and their values are listed -//! in NIST SP 800-90A Rev. 1, Table 2: Definitions for Hash-Based DRBG Mechanisms (p.38). -//! \details Some parameters have been reduce to fit C++ datatypes. For example, NIST allows upto -//! 248 requests before a reseed. However, Hash_DRBG limits it to INT_MAX due -//! to the limited data range of an int. -//! \sa Recommendation -//! for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) -//! \since Crypto++ 6.0 +/// \class Hash_DRBG +/// \tparam HASH NIST approved hash derived from HashTransformation +/// \tparam STRENGTH security strength, in bytes +/// \tparam SEEDLENGTH seed length, in bytes +/// \brief Hash_DRBG from SP 800-90A Rev 1 (June 2015) +/// \details The NIST Hash DRBG is instantiated with a number of parameters. Two of the parameters, +/// Security Strength and Seed Length, depend on the hash and are specified as template parameters. +/// The remaining parameters are included in the class. The parameters and their values are listed +/// in NIST SP 800-90A Rev. 1, Table 2: Definitions for Hash-Based DRBG Mechanisms (p.38). +/// \details Some parameters have been reduce to fit C++ datatypes. For example, NIST allows upto +/// 248 requests before a reseed. However, Hash_DRBG limits it to INT_MAX due +/// to the limited data range of an int. +/// \sa Recommendation +/// for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) +/// \since Crypto++ 6.0 template class Hash_DRBG : public NIST_DRBG, public NotCopyable { @@ -180,31 +180,31 @@ public: static std::string StaticAlgorithmName() { return std::string("Hash_DRBG(") + HASH::StaticAlgorithmName() + std::string(")"); } - //! \brief Construct a Hash DRBG - //! \param entropy the entropy to instantiate the generator - //! \param entropyLength the size of the entropy buffer - //! \param nonce additional input to instantiate the generator - //! \param nonceLength the size of the nonce buffer - //! \param personalization additional input to instantiate the generator - //! \param personalizationLength the size of the personalization buffer - //! \throws NIST_DRBG::Err if the generator is instantiated with insufficient entropy - //! \details All NIST DRBGs must be instaniated with at least MINIMUM_ENTROPY bytes of entropy. - //! The byte array for entropy must meet NIST - //! SP 800-90B or SP 800-90C requirements. - //! \details The nonce and personalization are optional byte arrays. If nonce is supplied, - //! then it should be at least MINIMUM_NONCE bytes of entropy. - //! \details An example of instantiating a SHA256 generator is shown below. - //! The example provides more entropy than required for SHA256. The NonblockingRng meets the - //! requirements of NIST SP 800-90B or SP 800-90C. - //! RDRAND() and RDSEED() generators would work as well. - //! 
-    //!    SecByteBlock entropy(48), result(128);
-    //!    NonblockingRng prng;
-    //!    RandomNumberSource rns(prng, entropy.size(), new ArraySink(entropy, entropy.size()));
-    //!
-    //!    Hash_DRBG drbg(entropy, 32, entropy+32, 16);
-    //!    drbg.GenerateBlock(result, result.size());
-    //!
+ /// \brief Construct a Hash DRBG + /// \param entropy the entropy to instantiate the generator + /// \param entropyLength the size of the entropy buffer + /// \param nonce additional input to instantiate the generator + /// \param nonceLength the size of the nonce buffer + /// \param personalization additional input to instantiate the generator + /// \param personalizationLength the size of the personalization buffer + /// \throws NIST_DRBG::Err if the generator is instantiated with insufficient entropy + /// \details All NIST DRBGs must be instaniated with at least MINIMUM_ENTROPY bytes of entropy. + /// The byte array for entropy must meet NIST + /// SP 800-90B or SP 800-90C requirements. + /// \details The nonce and personalization are optional byte arrays. If nonce is supplied, + /// then it should be at least MINIMUM_NONCE bytes of entropy. + /// \details An example of instantiating a SHA256 generator is shown below. + /// The example provides more entropy than required for SHA256. The NonblockingRng meets the + /// requirements of NIST SP 800-90B or SP 800-90C. + /// RDRAND() and RDSEED() generators would work as well. + /// 
+    ///    SecByteBlock entropy(48), result(128);
+    ///    NonblockingRng prng;
+    ///    RandomNumberSource rns(prng, entropy.size(), new ArraySink(entropy, entropy.size()));
+    ///
+    ///    Hash_DRBG drbg(entropy, 32, entropy+32, 16);
+    ///    drbg.GenerateBlock(result, result.size());
+    ///
Hash_DRBG(const byte* entropy=NULLPTR, size_t entropyLength=STRENGTH, const byte* nonce=NULLPTR, size_t nonceLength=0, const byte* personalization=NULLPTR, size_t personalizationLength=0) : NIST_DRBG(), m_c(SEEDLENGTH), m_v(SEEDLENGTH), m_reseed(0) @@ -261,20 +261,20 @@ private: // ************************************************************* -//! \class HMAC_DRBG -//! \tparam HASH NIST approved hash derived from HashTransformation -//! \tparam STRENGTH security strength, in bytes -//! \tparam SEEDLENGTH seed length, in bytes -//! \brief HMAC_DRBG from SP 800-90A Rev 1 (June 2015) -//! \details The NIST HMAC DRBG is instantiated with a number of parameters. Two of the parameters, -//! Security Strength and Seed Length, depend on the hash and are specified as template parameters. -//! The remaining parameters are included in the class. The parameters and their values are listed -//! in NIST SP 800-90A Rev. 1, Table 2: Definitions for Hash-Based DRBG Mechanisms (p.38). -//! \details Some parameters have been reduce to fit C++ datatypes. For example, NIST allows upto 248 requests -//! before a reseed. However, HMAC_DRBG limits it to INT_MAX due to the limited data range of an int. -//! \sa Recommendation -//! for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) -//! \since Crypto++ 6.0 +/// \class HMAC_DRBG +/// \tparam HASH NIST approved hash derived from HashTransformation +/// \tparam STRENGTH security strength, in bytes +/// \tparam SEEDLENGTH seed length, in bytes +/// \brief HMAC_DRBG from SP 800-90A Rev 1 (June 2015) +/// \details The NIST HMAC DRBG is instantiated with a number of parameters. Two of the parameters, +/// Security Strength and Seed Length, depend on the hash and are specified as template parameters. +/// The remaining parameters are included in the class. The parameters and their values are listed +/// in NIST SP 800-90A Rev. 1, Table 2: Definitions for Hash-Based DRBG Mechanisms (p.38). +/// \details Some parameters have been reduce to fit C++ datatypes. For example, NIST allows upto 248 requests +/// before a reseed. However, HMAC_DRBG limits it to INT_MAX due to the limited data range of an int. +/// \sa Recommendation +/// for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) +/// \since Crypto++ 6.0 template class HMAC_DRBG : public NIST_DRBG, public NotCopyable { @@ -294,31 +294,31 @@ public: static std::string StaticAlgorithmName() { return std::string("HMAC_DRBG(") + HASH::StaticAlgorithmName() + std::string(")"); } - //! \brief Construct a HMAC DRBG - //! \param entropy the entropy to instantiate the generator - //! \param entropyLength the size of the entropy buffer - //! \param nonce additional input to instantiate the generator - //! \param nonceLength the size of the nonce buffer - //! \param personalization additional input to instantiate the generator - //! \param personalizationLength the size of the personalization buffer - //! \throws NIST_DRBG::Err if the generator is instantiated with insufficient entropy - //! \details All NIST DRBGs must be instaniated with at least MINIMUM_ENTROPY bytes of entropy. - //! The byte array for entropy must meet NIST - //! SP 800-90B or SP 800-90C requirements. - //! \details The nonce and personalization are optional byte arrays. If nonce is supplied, - //! then it should be at least MINIMUM_NONCE bytes of entropy. - //! \details An example of instantiating a SHA256 generator is shown below. - //! The example provides more entropy than required for SHA256. The NonblockingRng meets the - //! requirements of NIST SP 800-90B or SP 800-90C. - //! RDRAND() and RDSEED() generators would work as well. - //! 
-    //!    SecByteBlock entropy(48), result(128);
-    //!    NonblockingRng prng;
-    //!    RandomNumberSource rns(prng, entropy.size(), new ArraySink(entropy, entropy.size()));
-    //!
-    //!    HMAC_DRBG drbg(entropy, 32, entropy+32, 16);
-    //!    drbg.GenerateBlock(result, result.size());
-    //!
+ /// \brief Construct a HMAC DRBG + /// \param entropy the entropy to instantiate the generator + /// \param entropyLength the size of the entropy buffer + /// \param nonce additional input to instantiate the generator + /// \param nonceLength the size of the nonce buffer + /// \param personalization additional input to instantiate the generator + /// \param personalizationLength the size of the personalization buffer + /// \throws NIST_DRBG::Err if the generator is instantiated with insufficient entropy + /// \details All NIST DRBGs must be instaniated with at least MINIMUM_ENTROPY bytes of entropy. + /// The byte array for entropy must meet NIST + /// SP 800-90B or SP 800-90C requirements. + /// \details The nonce and personalization are optional byte arrays. If nonce is supplied, + /// then it should be at least MINIMUM_NONCE bytes of entropy. + /// \details An example of instantiating a SHA256 generator is shown below. + /// The example provides more entropy than required for SHA256. The NonblockingRng meets the + /// requirements of NIST SP 800-90B or SP 800-90C. + /// RDRAND() and RDSEED() generators would work as well. + /// 
+    ///    SecByteBlock entropy(48), result(128);
+    ///    NonblockingRng prng;
+    ///    RandomNumberSource rns(prng, entropy.size(), new ArraySink(entropy, entropy.size()));
+    ///
+    ///    HMAC_DRBG drbg(entropy, 32, entropy+32, 16);
+    ///    drbg.GenerateBlock(result, result.size());
+    ///
HMAC_DRBG(const byte* entropy=NULLPTR, size_t entropyLength=STRENGTH, const byte* nonce=NULLPTR, size_t nonceLength=0, const byte* personalization=NULLPTR, size_t personalizationLength=0) : NIST_DRBG(), m_k(HASH::DIGESTSIZE), m_v(HASH::DIGESTSIZE), m_reseed(0) diff --git a/dsa.h b/dsa.h index 8ea4773f..21cd1a74 100644 --- a/dsa.h +++ b/dsa.h @@ -1,7 +1,7 @@ // dsa.h - originally written and placed in the public domain by Wei Dai -//! \file dsa.h -//! \brief Classes for the DSA signature algorithm +/// \file dsa.h +/// \brief Classes for the DSA signature algorithm #ifndef CRYPTOPP_DSA_H #define CRYPTOPP_DSA_H @@ -11,29 +11,29 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief DSA Signature Format -//! \details The DSA signature format used by Crypto++ is as defined by IEEE P1363. -//! Java nad .Net use the DER format, and OpenPGP uses the OpenPGP format. +/// \brief DSA Signature Format +/// \details The DSA signature format used by Crypto++ is as defined by IEEE P1363. +/// Java nad .Net use the DER format, and OpenPGP uses the OpenPGP format. enum DSASignatureFormat { - //! \brief Crypto++ native signature encoding format + /// \brief Crypto++ native signature encoding format DSA_P1363, - //! \brief signature encoding format used by Java and .Net + /// \brief signature encoding format used by Java and .Net DSA_DER, - //! \brief OpenPGP signature encoding format + /// \brief OpenPGP signature encoding format DSA_OPENPGP }; -//! \brief Converts between signature encoding formats -//! \param buffer byte buffer for the converted signature encoding -//! \param bufferSize the length of the converted signature encoding buffer -//! \param toFormat the source signature format -//! \param signature byte buffer for the existing signature encoding -//! \param signatureLen the length of the existing signature encoding buffer -//! \param fromFormat the source signature format -//! \details This function converts between these formats, and returns length -//! of signature in the target format. If toFormat == DSA_P1363, then -//! bufferSize must equal publicKey.SignatureLength() -//! \since Crypto++ 1.0 +/// \brief Converts between signature encoding formats +/// \param buffer byte buffer for the converted signature encoding +/// \param bufferSize the length of the converted signature encoding buffer +/// \param toFormat the source signature format +/// \param signature byte buffer for the existing signature encoding +/// \param signatureLen the length of the existing signature encoding buffer +/// \param fromFormat the source signature format +/// \details This function converts between these formats, and returns length +/// of signature in the target format. If toFormat == DSA_P1363, then +/// bufferSize must equal publicKey.SignatureLength() +/// \since Crypto++ 1.0 size_t DSAConvertSignatureFormat(byte *buffer, size_t bufferSize, DSASignatureFormat toFormat, const byte *signature, size_t signatureLen, DSASignatureFormat fromFormat); diff --git a/eax.h b/eax.h index 3a17658b..f9917fe1 100644 --- a/eax.h +++ b/eax.h @@ -1,7 +1,7 @@ // eax.h - originally written and placed in the public domain by Wei Dai -//! \file eax.h -//! \brief EAX block cipher mode of operation +/// \file eax.h +/// \brief EAX block cipher mode of operation #ifndef CRYPTOPP_EAX_H #define CRYPTOPP_EAX_H @@ -12,10 +12,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class EAX_Base -//! \brief EAX block cipher base implementation -//! \details Base implementation of the AuthenticatedSymmetricCipher interface -//! \since Crypto++ 5.6.0 +/// \class EAX_Base +/// \brief EAX block cipher base implementation +/// \details Base implementation of the AuthenticatedSymmetricCipher interface +/// \since Crypto++ 5.6.0 class CRYPTOPP_NO_VTABLE EAX_Base : public AuthenticatedSymmetricCipherBase { public: @@ -67,11 +67,11 @@ protected: CTR_Mode_ExternalCipher::Encryption m_ctr; }; -//! \class EAX_Final -//! \brief EAX block cipher final implementation -//! \tparam T_BlockCipher block cipher -//! \tparam T_IsEncryption direction in which to operate the cipher -//! \since Crypto++ 5.6.0 +/// \class EAX_Final +/// \brief EAX block cipher final implementation +/// \tparam T_BlockCipher block cipher +/// \tparam T_IsEncryption direction in which to operate the cipher +/// \since Crypto++ 5.6.0 template class EAX_Final : public EAX_Base { @@ -90,15 +90,15 @@ private: #undef EAX #endif -//! \class EAX -//! \brief EAX block cipher mode of operation -//! \tparam T_BlockCipher block cipher -//! \details \p EAX provides the \p Encryption and \p Decryption typedef. See EAX_Base -//! and EAX_Final for the AuthenticatedSymmetricCipher implementation. -//! \sa EAX Mode and -//! Modes of Operation -//! on the Crypto++ wiki. -//! \since Crypto++ 5.6.0 +/// \class EAX +/// \brief EAX block cipher mode of operation +/// \tparam T_BlockCipher block cipher +/// \details \p EAX provides the \p Encryption and \p Decryption typedef. See EAX_Base +/// and EAX_Final for the AuthenticatedSymmetricCipher implementation. +/// \sa EAX Mode and +/// Modes of Operation +/// on the Crypto++ wiki. +/// \since Crypto++ 5.6.0 template struct EAX : public AuthenticatedSymmetricCipherDocumentation { diff --git a/ec2n.h b/ec2n.h index cc4c0462..6de58c62 100644 --- a/ec2n.h +++ b/ec2n.h @@ -1,8 +1,8 @@ // ec2n.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile ec2n.h -//! \brief Classes for Elliptic Curves over binary fields +/// \file +/// \headerfile ec2n.h +/// \brief Classes for Elliptic Curves over binary fields #ifndef CRYPTOPP_EC2N_H @@ -24,8 +24,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class EC2N -//! \brief Elliptic Curve over GF(2^n) +/// \class EC2N +/// \brief Elliptic Curve over GF(2^n) class CRYPTOPP_DLL EC2N : public AbstractGroup, public EncodedPoint { public: @@ -35,23 +35,23 @@ public: virtual ~EC2N() {} - //! \brief Construct an EC2N + /// \brief Construct an EC2N EC2N() {} - //! \brief Construct an EC2N - //! \param field Field, GF2NP derived class - //! \param a Field::Element - //! \param b Field::Element + /// \brief Construct an EC2N + /// \param field Field, GF2NP derived class + /// \param a Field::Element + /// \param b Field::Element EC2N(const Field &field, const Field::Element &a, const Field::Element &b) : m_field(field), m_a(a), m_b(b) {} - //! \brief Construct an EC2N from BER encoded parameters - //! \param bt BufferedTransformation derived object - //! \details This constructor will decode and extract the the fields fieldID and curve of the sequence ECParameters + /// \brief Construct an EC2N from BER encoded parameters + /// \param bt BufferedTransformation derived object + /// \details This constructor will decode and extract the the fields fieldID and curve of the sequence ECParameters EC2N(BufferedTransformation &bt); - //! \brief Encode the fields fieldID and curve of the sequence ECParameters - //! \param bt BufferedTransformation derived object + /// \brief Encode the fields fieldID and curve of the sequence ECParameters + /// \param bt BufferedTransformation derived object void DEREncode(BufferedTransformation &bt) const; bool Equal(const Point &P, const Point &Q) const; @@ -97,15 +97,15 @@ private: CRYPTOPP_DLL_TEMPLATE_CLASS DL_FixedBasePrecomputationImpl; CRYPTOPP_DLL_TEMPLATE_CLASS DL_GroupPrecomputation; -//! \class EcPrecomputation -//! \brief Elliptic Curve precomputation -//! \tparam EC elliptic curve field +/// \class EcPrecomputation +/// \brief Elliptic Curve precomputation +/// \tparam EC elliptic curve field template class EcPrecomputation; -//! \class EcPrecomputation -//! \brief EC2N precomputation specialization -//! \details Implementation of DL_GroupPrecomputation -//! \sa DL_GroupPrecomputation +/// \class EcPrecomputation +/// \brief EC2N precomputation specialization +/// \details Implementation of DL_GroupPrecomputation +/// \sa DL_GroupPrecomputation template<> class EcPrecomputation : public DL_GroupPrecomputation { public: diff --git a/eccrypto.h b/eccrypto.h index f6016c07..3072f592 100644 --- a/eccrypto.h +++ b/eccrypto.h @@ -1,8 +1,8 @@ // eccrypto.h - originally written and placed in the public domain by Wei Dai // deterministic signatures added by by Douglas Roark -//! \file eccrypto.h -//! \brief Classes and functions for Elliptic Curves over prime and binary fields +/// \file eccrypto.h +/// \brief Classes and functions for Elliptic Curves over prime and binary fields #ifndef CRYPTOPP_ECCRYPTO_H #define CRYPTOPP_ECCRYPTO_H @@ -29,10 +29,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Elliptic Curve Parameters -//! \tparam EC elliptic curve field -//! \details This class corresponds to the ASN.1 sequence of the same name -//! in ANSI X9.62 and SEC 1. EC is currently defined for ECP and EC2N. +/// \brief Elliptic Curve Parameters +/// \tparam EC elliptic curve field +/// \details This class corresponds to the ASN.1 sequence of the same name +/// in ANSI X9.62 and SEC 1. EC is currently defined for ECP and EC2N. template class DL_GroupParameters_EC : public DL_GroupParametersImpl > { @@ -46,33 +46,33 @@ public: virtual ~DL_GroupParameters_EC() {} - //! \brief Construct an EC GroupParameters + /// \brief Construct an EC GroupParameters DL_GroupParameters_EC() : m_compress(false), m_encodeAsOID(true) {} - //! \brief Construct an EC GroupParameters - //! \param oid the OID of a curve + /// \brief Construct an EC GroupParameters + /// \param oid the OID of a curve DL_GroupParameters_EC(const OID &oid) : m_compress(false), m_encodeAsOID(true) {Initialize(oid);} - //! \brief Construct an EC GroupParameters - //! \param ec the elliptic curve - //! \param G the base point - //! \param n the order of the base point - //! \param k the cofactor + /// \brief Construct an EC GroupParameters + /// \param ec the elliptic curve + /// \param G the base point + /// \param n the order of the base point + /// \param k the cofactor DL_GroupParameters_EC(const EllipticCurve &ec, const Point &G, const Integer &n, const Integer &k = Integer::Zero()) : m_compress(false), m_encodeAsOID(true) {Initialize(ec, G, n, k);} - //! \brief Construct an EC GroupParameters - //! \param bt BufferedTransformation with group parameters + /// \brief Construct an EC GroupParameters + /// \param bt BufferedTransformation with group parameters DL_GroupParameters_EC(BufferedTransformation &bt) : m_compress(false), m_encodeAsOID(true) {BERDecode(bt);} - //! \brief Initialize an EC GroupParameters using {EC,G,n,k} - //! \param ec the elliptic curve - //! \param G the base point - //! \param n the order of the base point - //! \param k the cofactor - //! \details This Initialize() function overload initializes group parameters from existing parameters. + /// \brief Initialize an EC GroupParameters using {EC,G,n,k} + /// \param ec the elliptic curve + /// \param G the base point + /// \param n the order of the base point + /// \param k the cofactor + /// \details This Initialize() function overload initializes group parameters from existing parameters. void Initialize(const EllipticCurve &ec, const Point &G, const Integer &n, const Integer &k = Integer::Zero()) { this->m_groupPrecomputation.SetCurve(ec); @@ -81,9 +81,9 @@ public: m_k = k; } - //! \brief Initialize a DL_GroupParameters_EC {EC,G,n,k} - //! \param oid the OID of a curve - //! \details This Initialize() function overload initializes group parameters from existing parameters. + /// \brief Initialize a DL_GroupParameters_EC {EC,G,n,k} + /// \param oid the OID of a curve + /// \details This Initialize() function overload initializes group parameters from existing parameters. void Initialize(const OID &oid); // NameValuePairs @@ -91,7 +91,7 @@ public: void AssignFrom(const NameValuePairs &source); // GeneratibleCryptoMaterial interface - //! this implementation doesn't actually generate a curve, it just initializes the parameters with existing values + /// this implementation doesn't actually generate a curve, it just initializes the parameters with existing values /*! parameters: (Curve, SubgroupGenerator, SubgroupOrder, Cofactor (optional)), or (GroupOID) */ void GenerateRandom(RandomNumberGenerator &rng, const NameValuePairs &alg); @@ -174,9 +174,9 @@ protected: mutable bool m_compress, m_encodeAsOID; // presentation details }; -//! \class DL_PublicKey_EC -//! \brief Elliptic Curve Discrete Log (DL) public key -//! \tparam EC elliptic curve field +/// \class DL_PublicKey_EC +/// \brief Elliptic Curve Discrete Log (DL) public key +/// \tparam EC elliptic curve field template class DL_PublicKey_EC : public DL_PublicKeyImpl > { @@ -185,19 +185,19 @@ public: virtual ~DL_PublicKey_EC() {} - //! \brief Initialize an EC Public Key using {GP,Q} - //! \param params group parameters - //! \param Q the public point - //! \details This Initialize() function overload initializes a public key from existing parameters. + /// \brief Initialize an EC Public Key using {GP,Q} + /// \param params group parameters + /// \param Q the public point + /// \details This Initialize() function overload initializes a public key from existing parameters. void Initialize(const DL_GroupParameters_EC ¶ms, const Element &Q) {this->AccessGroupParameters() = params; this->SetPublicElement(Q);} - //! \brief Initialize an EC Public Key using {EC,G,n,Q} - //! \param ec the elliptic curve - //! \param G the base point - //! \param n the order of the base point - //! \param Q the public point - //! \details This Initialize() function overload initializes a public key from existing parameters. + /// \brief Initialize an EC Public Key using {EC,G,n,Q} + /// \param ec the elliptic curve + /// \param G the base point + /// \param n the order of the base point + /// \param Q the public point + /// \details This Initialize() function overload initializes a public key from existing parameters. void Initialize(const EC &ec, const Element &G, const Integer &n, const Element &Q) {this->AccessGroupParameters().Initialize(ec, G, n); this->SetPublicElement(Q);} @@ -206,9 +206,9 @@ public: void DEREncodePublicKey(BufferedTransformation &bt) const; }; -//! \class DL_PrivateKey_EC -//! \brief Elliptic Curve Discrete Log (DL) private key -//! \tparam EC elliptic curve field +/// \class DL_PrivateKey_EC +/// \brief Elliptic Curve Discrete Log (DL) private key +/// \tparam EC elliptic curve field template class DL_PrivateKey_EC : public DL_PrivateKeyImpl > { @@ -217,39 +217,39 @@ public: virtual ~DL_PrivateKey_EC(); - //! \brief Initialize an EC Private Key using {GP,x} - //! \param params group parameters - //! \param x the private exponent - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize an EC Private Key using {GP,x} + /// \param params group parameters + /// \param x the private exponent + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const DL_GroupParameters_EC ¶ms, const Integer &x) {this->AccessGroupParameters() = params; this->SetPrivateExponent(x);} - //! \brief Initialize an EC Private Key using {EC,G,n,x} - //! \param ec the elliptic curve - //! \param G the base point - //! \param n the order of the base point - //! \param x the private exponent - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize an EC Private Key using {EC,G,n,x} + /// \param ec the elliptic curve + /// \param G the base point + /// \param n the order of the base point + /// \param x the private exponent + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const EC &ec, const Element &G, const Integer &n, const Integer &x) {this->AccessGroupParameters().Initialize(ec, G, n); this->SetPrivateExponent(x);} - //! \brief Create an EC private key - //! \param rng a RandomNumberGenerator derived class - //! \param params the EC group parameters - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create an EC private key + /// \param rng a RandomNumberGenerator derived class + /// \param params the EC group parameters + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const DL_GroupParameters_EC ¶ms) {this->GenerateRandom(rng, params);} - //! \brief Create an EC private key - //! \param rng a RandomNumberGenerator derived class - //! \param ec the elliptic curve - //! \param G the base point - //! \param n the order of the base point - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create an EC private key + /// \param rng a RandomNumberGenerator derived class + /// \param ec the elliptic curve + /// \param G the base point + /// \param n the order of the base point + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const EC &ec, const Element &G, const Integer &n) {this->GenerateRandom(rng, DL_GroupParameters_EC(ec, G, n));} @@ -262,21 +262,21 @@ public: template DL_PrivateKey_EC::~DL_PrivateKey_EC() {} -//! \class ECDH -//! \brief Elliptic Curve Diffie-Hellman -//! \tparam EC elliptic curve field -//! \tparam COFACTOR_OPTION cofactor multiplication option -//! \sa CofactorMultiplicationOption, Elliptic Curve Diffie-Hellman, AKA ECDH +/// \class ECDH +/// \brief Elliptic Curve Diffie-Hellman +/// \tparam EC elliptic curve field +/// \tparam COFACTOR_OPTION cofactor multiplication option +/// \sa CofactorMultiplicationOption, Elliptic Curve Diffie-Hellman, AKA ECDH template ::DefaultCofactorOption> struct ECDH { typedef DH_Domain, COFACTOR_OPTION> Domain; }; -//! \class ECMQV -//! \brief Elliptic Curve Menezes-Qu-Vanstone -//! \tparam EC elliptic curve field -//! \tparam COFACTOR_OPTION cofactor multiplication option +/// \class ECMQV +/// \brief Elliptic Curve Menezes-Qu-Vanstone +/// \tparam EC elliptic curve field +/// \tparam COFACTOR_OPTION cofactor multiplication option /// \sa CofactorMultiplicationOption, Elliptic Curve Menezes-Qu-Vanstone, AKA ECMQV template ::DefaultCofactorOption> struct ECMQV @@ -284,13 +284,13 @@ struct ECMQV typedef MQV_Domain, COFACTOR_OPTION> Domain; }; -//! \class ECHMQV -//! \brief Hashed Elliptic Curve Menezes-Qu-Vanstone -//! \tparam EC elliptic curve field -//! \tparam COFACTOR_OPTION cofactor multiplication option -//! \details This implementation follows Hugo Krawczyk's HMQV: A High-Performance -//! Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided. -//! \sa CofactorMultiplicationOption +/// \class ECHMQV +/// \brief Hashed Elliptic Curve Menezes-Qu-Vanstone +/// \tparam EC elliptic curve field +/// \tparam COFACTOR_OPTION cofactor multiplication option +/// \details This implementation follows Hugo Krawczyk's HMQV: A High-Performance +/// Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided. +/// \sa CofactorMultiplicationOption template ::DefaultCofactorOption, class HASH = SHA256> struct ECHMQV { @@ -302,14 +302,14 @@ typedef ECHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA256 typedef ECHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA384 >::Domain ECHMQV384; typedef ECHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA512 >::Domain ECHMQV512; -//! \class ECFHMQV -//! \brief Fully Hashed Elliptic Curve Menezes-Qu-Vanstone -//! \tparam EC elliptic curve field -//! \tparam COFACTOR_OPTION cofactor multiplication option -//! \details This implementation follows Augustin P. Sarr and Philippe Elbaz–Vincent, and Jean–Claude Bajard's -//! A Secure and Efficient Authenticated Diffie-Hellman Protocol. -//! Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C. -//! \sa CofactorMultiplicationOption +/// \class ECFHMQV +/// \brief Fully Hashed Elliptic Curve Menezes-Qu-Vanstone +/// \tparam EC elliptic curve field +/// \tparam COFACTOR_OPTION cofactor multiplication option +/// \details This implementation follows Augustin P. Sarr and Philippe Elbaz–Vincent, and Jean–Claude Bajard's +/// A Secure and Efficient Authenticated Diffie-Hellman Protocol. +/// Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C. +/// \sa CofactorMultiplicationOption template ::DefaultCofactorOption, class HASH = SHA256> struct ECFHMQV { @@ -321,9 +321,9 @@ typedef ECFHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA25 typedef ECFHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA384 >::Domain ECFHMQV384; typedef ECFHMQV< ECP, DL_GroupParameters_EC< ECP >::DefaultCofactorOption, SHA512 >::Domain ECFHMQV512; -//! \class DL_Keys_EC -//! \brief Elliptic Curve Discrete Log (DL) keys -//! \tparam EC elliptic curve field +/// \class DL_Keys_EC +/// \brief Elliptic Curve Discrete Log (DL) keys +/// \tparam EC elliptic curve field template struct DL_Keys_EC { @@ -335,9 +335,9 @@ struct DL_Keys_EC template struct ECDSA; -//! \class DL_Keys_ECDSA -//! \brief Elliptic Curve DSA keys -//! \tparam EC elliptic curve field +/// \class DL_Keys_ECDSA +/// \brief Elliptic Curve DSA keys +/// \tparam EC elliptic curve field template struct DL_Keys_ECDSA { @@ -345,9 +345,9 @@ struct DL_Keys_ECDSA typedef DL_PrivateKey_WithSignaturePairwiseConsistencyTest, ECDSA > PrivateKey; }; -//! \class DL_Algorithm_ECDSA -//! \brief Elliptic Curve DSA (ECDSA) signature algorithm -//! \tparam EC elliptic curve field +/// \class DL_Algorithm_ECDSA +/// \brief Elliptic Curve DSA (ECDSA) signature algorithm +/// \tparam EC elliptic curve field template class DL_Algorithm_ECDSA : public DL_Algorithm_GDSA { @@ -355,12 +355,12 @@ public: CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "ECDSA";} }; -//! \class DL_Algorithm_ECDSA_RFC6979 -//! \brief Elliptic Curve DSA (ECDSA) signature algorithm based on RFC 6979 -//! \tparam EC elliptic curve field -//! \sa RFC 6979, Deterministic Usage of the -//! Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) -//! \since Crypto++ 6.0 +/// \class DL_Algorithm_ECDSA_RFC6979 +/// \brief Elliptic Curve DSA (ECDSA) signature algorithm based on RFC 6979 +/// \tparam EC elliptic curve field +/// \sa RFC 6979, Deterministic Usage of the +/// Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) +/// \since Crypto++ 6.0 template class DL_Algorithm_ECDSA_RFC6979 : public DL_Algorithm_DSA_RFC6979 { @@ -368,9 +368,9 @@ public: CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "ECDSA-RFC6979";} }; -//! \class DL_Algorithm_ECNR -//! \brief Elliptic Curve NR (ECNR) signature algorithm -//! \tparam EC elliptic curve field +/// \class DL_Algorithm_ECNR +/// \brief Elliptic Curve NR (ECNR) signature algorithm +/// \tparam EC elliptic curve field template class DL_Algorithm_ECNR : public DL_Algorithm_NR { @@ -378,22 +378,22 @@ public: CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "ECNR";} }; -//! \class ECDSA -//! \brief Elliptic Curve DSA (ECDSA) signature scheme -//! \tparam EC elliptic curve field -//! \tparam H HashTransformation derived class -//! \sa ECDSA +/// \class ECDSA +/// \brief Elliptic Curve DSA (ECDSA) signature scheme +/// \tparam EC elliptic curve field +/// \tparam H HashTransformation derived class +/// \sa ECDSA template struct ECDSA : public DL_SS, DL_Algorithm_ECDSA, DL_SignatureMessageEncodingMethod_DSA, H> { }; -//! \class ECDSA_RFC6979 -//! \brief Elliptic Curve DSA (ECDSA) deterministic signature scheme -//! \tparam EC elliptic curve field -//! \tparam H HashTransformation derived class -//! \sa Deterministic Usage of the -//! Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) +/// \class ECDSA_RFC6979 +/// \brief Elliptic Curve DSA (ECDSA) deterministic signature scheme +/// \tparam EC elliptic curve field +/// \tparam H HashTransformation derived class +/// \sa Deterministic Usage of the +/// Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) template struct ECDSA_RFC6979 : public DL_SS< DL_Keys_ECDSA, @@ -405,10 +405,10 @@ struct ECDSA_RFC6979 : public DL_SS< static std::string CRYPTOPP_API StaticAlgorithmName() {return std::string("ECDSA-RFC6979/") + H::StaticAlgorithmName();} }; -//! \class ECNR -//! \brief Elliptic Curve NR (ECNR) signature scheme -//! \tparam EC elliptic curve field -//! \tparam H HashTransformation derived class +/// \class ECNR +/// \brief Elliptic Curve NR (ECNR) signature scheme +/// \tparam EC elliptic curve field +/// \tparam H HashTransformation derived class template struct ECNR : public DL_SS, DL_Algorithm_ECNR, DL_SignatureMessageEncodingMethod_NR, H> { @@ -421,11 +421,11 @@ class DL_PublicKey_ECGDSA_ISO15946; template class DL_PrivateKey_ECGDSA_ISO15946; -//! \class DL_PrivateKey_ECGDSA_ISO15946 -//! \brief Elliptic Curve German DSA key for ISO/IEC 15946 -//! \tparam EC elliptic curve field -//! \sa ECGDSA_ISO15946 -//! \since Crypto++ 6.0 +/// \class DL_PrivateKey_ECGDSA_ISO15946 +/// \brief Elliptic Curve German DSA key for ISO/IEC 15946 +/// \tparam EC elliptic curve field +/// \sa ECGDSA_ISO15946 +/// \since Crypto++ 6.0 template class DL_PrivateKey_ECGDSA_ISO15946 : public DL_PrivateKeyImpl > { @@ -434,10 +434,10 @@ public: virtual ~DL_PrivateKey_ECGDSA_ISO15946() {} - //! \brief Initialize an EC Private Key using {GP,x} - //! \param params group parameters - //! \param x the private exponent - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize an EC Private Key using {GP,x} + /// \param params group parameters + /// \param x the private exponent + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const DL_GroupParameters_EC ¶ms, const Integer &x) { this->AccessGroupParameters() = params; @@ -445,12 +445,12 @@ public: CRYPTOPP_ASSERT(x>=1 && x<=params.GetSubgroupOrder()-1); } - //! \brief Initialize an EC Private Key using {EC,G,n,x} - //! \param ec the elliptic curve - //! \param G the base point - //! \param n the order of the base point - //! \param x the private exponent - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize an EC Private Key using {EC,G,n,x} + /// \param ec the elliptic curve + /// \param G the base point + /// \param n the order of the base point + /// \param x the private exponent + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const EC &ec, const Element &G, const Integer &n, const Integer &x) { this->AccessGroupParameters().Initialize(ec, G, n); @@ -458,23 +458,23 @@ public: CRYPTOPP_ASSERT(x>=1 && x<=this->AccessGroupParameters().GetSubgroupOrder()-1); } - //! \brief Create an EC private key - //! \param rng a RandomNumberGenerator derived class - //! \param params the EC group parameters - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create an EC private key + /// \param rng a RandomNumberGenerator derived class + /// \param params the EC group parameters + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const DL_GroupParameters_EC ¶ms) {this->GenerateRandom(rng, params);} - //! \brief Create an EC private key - //! \param rng a RandomNumberGenerator derived class - //! \param ec the elliptic curve - //! \param G the base point - //! \param n the order of the base point - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create an EC private key + /// \param rng a RandomNumberGenerator derived class + /// \param ec the elliptic curve + /// \param G the base point + /// \param n the order of the base point + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const EC &ec, const Element &G, const Integer &n) {this->GenerateRandom(rng, DL_GroupParameters_EC(ec, G, n));} @@ -504,11 +504,11 @@ public: void DEREncodePrivateKey(BufferedTransformation &bt) const; }; -//! \class DL_PublicKey_ECGDSA_ISO15946 -//! \brief Elliptic Curve German DSA key for ISO/IEC 15946 -//! \tparam EC elliptic curve field -//! \sa ECGDSA_ISO15946 -//! \since Crypto++ 6.0 +/// \class DL_PublicKey_ECGDSA_ISO15946 +/// \brief Elliptic Curve German DSA key for ISO/IEC 15946 +/// \tparam EC elliptic curve field +/// \sa ECGDSA_ISO15946 +/// \since Crypto++ 6.0 template class DL_PublicKey_ECGDSA_ISO15946 : public DL_PublicKeyImpl > { @@ -519,19 +519,19 @@ public: virtual ~DL_PublicKey_ECGDSA_ISO15946() {} - //! \brief Initialize an EC Public Key using {GP,Q} - //! \param params group parameters - //! \param Q the public point - //! \details This Initialize() function overload initializes a public key from existing parameters. + /// \brief Initialize an EC Public Key using {GP,Q} + /// \param params group parameters + /// \param Q the public point + /// \details This Initialize() function overload initializes a public key from existing parameters. void Initialize(const DL_GroupParameters_EC ¶ms, const Element &Q) {this->AccessGroupParameters() = params; this->SetPublicElement(Q);} - //! \brief Initialize an EC Public Key using {EC,G,n,Q} - //! \param ec the elliptic curve - //! \param G the base point - //! \param n the order of the base point - //! \param Q the public point - //! \details This Initialize() function overload initializes a public key from existing parameters. + /// \brief Initialize an EC Public Key using {EC,G,n,Q} + /// \param ec the elliptic curve + /// \param G the base point + /// \param n the order of the base point + /// \param Q the public point + /// \details This Initialize() function overload initializes a public key from existing parameters. void Initialize(const EC &ec, const Element &G, const Integer &n, const Element &Q) {this->AccessGroupParameters().Initialize(ec, G, n); this->SetPublicElement(Q);} @@ -557,11 +557,11 @@ public: void DEREncodePublicKey(BufferedTransformation &bt) const; }; -//! \class DL_Keys_ECGDSA_ISO15946 -//! \brief Elliptic Curve German DSA keys for ISO/IEC 15946 -//! \tparam EC elliptic curve field -//! \sa ECGDSA_ISO15946 -//! \since Crypto++ 6.0 +/// \class DL_Keys_ECGDSA_ISO15946 +/// \brief Elliptic Curve German DSA keys for ISO/IEC 15946 +/// \tparam EC elliptic curve field +/// \sa ECGDSA_ISO15946 +/// \since Crypto++ 6.0 template struct DL_Keys_ECGDSA_ISO15946 { @@ -569,11 +569,11 @@ struct DL_Keys_ECGDSA_ISO15946 typedef DL_PrivateKey_ECGDSA_ISO15946 PrivateKey; }; -//! \class DL_Algorithm_ECGDSA_ISO15946 -//! \brief Elliptic Curve German DSA signature algorithm -//! \tparam EC elliptic curve field -//! \sa ECGDSA_ISO15946 -//! \since Crypto++ 6.0 +/// \class DL_Algorithm_ECGDSA_ISO15946 +/// \brief Elliptic Curve German DSA signature algorithm +/// \tparam EC elliptic curve field +/// \sa ECGDSA_ISO15946 +/// \since Crypto++ 6.0 template class DL_Algorithm_ECGDSA_ISO15946 : public DL_Algorithm_GDSA_ISO15946 { @@ -581,14 +581,14 @@ public: CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "ECGDSA";} }; -//! \class ECGDSA -//! \brief Elliptic Curve German Digital Signature Algorithm signature scheme -//! \tparam EC elliptic curve field -//! \tparam H HashTransformation derived class -//! \sa Erwin Hess, Marcus Schafheutle, and Pascale Serf The Digital Signature Scheme -//! ECGDSA (October 24, 2006) -//! \since Crypto++ 6.0 +/// \class ECGDSA +/// \brief Elliptic Curve German Digital Signature Algorithm signature scheme +/// \tparam EC elliptic curve field +/// \tparam H HashTransformation derived class +/// \sa Erwin Hess, Marcus Schafheutle, and Pascale Serf The Digital Signature Scheme +/// ECGDSA (October 24, 2006) +/// \since Crypto++ 6.0 template struct ECGDSA : public DL_SS< DL_Keys_ECGDSA_ISO15946, @@ -601,40 +601,40 @@ struct ECGDSA : public DL_SS< // ****************************************** -//! \class ECIES -//! \brief Elliptic Curve Integrated Encryption Scheme -//! \tparam COFACTOR_OPTION cofactor multiplication option -//! \tparam HASH HashTransformation derived class used for key drivation and MAC computation -//! \tparam DHAES_MODE flag indicating if the MAC includes additional context parameters such as u·V, v·U and label -//! \tparam LABEL_OCTETS flag indicating if the label size is specified in octets or bits -//! \details ECIES is an Elliptic Curve based Integrated Encryption Scheme (IES). The scheme combines a Key Encapsulation -//! Method (KEM) with a Data Encapsulation Method (DEM) and a MAC tag. The scheme is -//! IND-CCA2, which is a strong notion of security. -//! You should prefer an Integrated Encryption Scheme over homegrown schemes. -//! \details The library's original implementation is based on an early P1363 draft, which itself appears to be based on an early Certicom -//! SEC-1 draft (or an early SEC-1 draft was based on a P1363 draft). Crypto++ 4.2 used the early draft in its Integrated Ecryption -//! Schemes with NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. -//! \details If you desire an Integrated Encryption Scheme with Crypto++ 4.2 compatibility, then use the ECIES template class with -//! NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. -//! \details If you desire an Integrated Encryption Scheme with Bouncy Castle 1.54 and Botan 1.11 compatibility, then use the ECIES -//! template class with NoCofactorMultiplication, DHAES_MODE=true and LABEL_OCTETS=false. -//! \details The default template parameters ensure compatibility with Bouncy Castle 1.54 and Botan 1.11. The combination of -//! IncompatibleCofactorMultiplication and DHAES_MODE=true is recommended for best efficiency and security. -//! SHA1 is used for compatibility reasons, but it can be changed if desired. SHA-256 or another hash will likely improve the -//! security provided by the MAC. The hash is also used in the key derivation function as a PRF. -//! \details Below is an example of constructing a Crypto++ 4.2 compatible ECIES encryptor and decryptor. -//! 
-//!     AutoSeededRandomPool prng;
-//!     DL_PrivateKey_EC key;
-//!     key.Initialize(prng, ASN1::secp160r1());
-//!
-//!     ECIES::Decryptor decryptor(key);
-//!     ECIES::Encryptor encryptor(decryptor);
-//!
-//! \sa DLIES, Elliptic Curve Integrated Encryption Scheme (ECIES), -//! Martínez, Encinas, and Ávila's A Survey of the Elliptic -//! Curve Integrated Encryption Schemes -//! \since Crypto++ 4.0, Crypto++ 5.7 for Bouncy Castle and Botan compatibility +/// \class ECIES +/// \brief Elliptic Curve Integrated Encryption Scheme +/// \tparam COFACTOR_OPTION cofactor multiplication option +/// \tparam HASH HashTransformation derived class used for key drivation and MAC computation +/// \tparam DHAES_MODE flag indicating if the MAC includes additional context parameters such as u·V, v·U and label +/// \tparam LABEL_OCTETS flag indicating if the label size is specified in octets or bits +/// \details ECIES is an Elliptic Curve based Integrated Encryption Scheme (IES). The scheme combines a Key Encapsulation +/// Method (KEM) with a Data Encapsulation Method (DEM) and a MAC tag. The scheme is +/// IND-CCA2, which is a strong notion of security. +/// You should prefer an Integrated Encryption Scheme over homegrown schemes. +/// \details The library's original implementation is based on an early P1363 draft, which itself appears to be based on an early Certicom +/// SEC-1 draft (or an early SEC-1 draft was based on a P1363 draft). Crypto++ 4.2 used the early draft in its Integrated Ecryption +/// Schemes with NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. +/// \details If you desire an Integrated Encryption Scheme with Crypto++ 4.2 compatibility, then use the ECIES template class with +/// NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. +/// \details If you desire an Integrated Encryption Scheme with Bouncy Castle 1.54 and Botan 1.11 compatibility, then use the ECIES +/// template class with NoCofactorMultiplication, DHAES_MODE=true and LABEL_OCTETS=false. +/// \details The default template parameters ensure compatibility with Bouncy Castle 1.54 and Botan 1.11. The combination of +/// IncompatibleCofactorMultiplication and DHAES_MODE=true is recommended for best efficiency and security. +/// SHA1 is used for compatibility reasons, but it can be changed if desired. SHA-256 or another hash will likely improve the +/// security provided by the MAC. The hash is also used in the key derivation function as a PRF. +/// \details Below is an example of constructing a Crypto++ 4.2 compatible ECIES encryptor and decryptor. +/// 
+///     AutoSeededRandomPool prng;
+///     DL_PrivateKey_EC key;
+///     key.Initialize(prng, ASN1::secp160r1());
+///
+///     ECIES::Decryptor decryptor(key);
+///     ECIES::Encryptor encryptor(decryptor);
+///
+/// \sa DLIES, Elliptic Curve Integrated Encryption Scheme (ECIES), +/// Martínez, Encinas, and Ávila's A Survey of the Elliptic +/// Curve Integrated Encryption Schemes +/// \since Crypto++ 4.0, Crypto++ 5.7 for Bouncy Castle and Botan compatibility template struct ECIES : public DL_ES< diff --git a/ecp.h b/ecp.h index 082eb636..2199b8c3 100644 --- a/ecp.h +++ b/ecp.h @@ -1,7 +1,7 @@ // ecp.h - originally written and placed in the public domain by Wei Dai -//! \file ecp.h -//! \brief Classes for Elliptic Curves over prime fields +/// \file ecp.h +/// \brief Classes for Elliptic Curves over prime fields #ifndef CRYPTOPP_ECP_H #define CRYPTOPP_ECP_H @@ -22,8 +22,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ECP -//! \brief Elliptic Curve over GF(p), where p is prime +/// \class ECP +/// \brief Elliptic Curve over GF(p), where p is prime class CRYPTOPP_DLL ECP : public AbstractGroup, public EncodedPoint { public: @@ -33,29 +33,29 @@ public: virtual ~ECP() {} - //! \brief Construct an ECP + /// \brief Construct an ECP ECP() {} - //! \brief Copy construct an ECP - //! \param ecp the other ECP object - //! \param convertToMontgomeryRepresentation flag indicating if the curve should be converted to a MontgomeryRepresentation - //! \sa ModularArithmetic, MontgomeryRepresentation + /// \brief Copy construct an ECP + /// \param ecp the other ECP object + /// \param convertToMontgomeryRepresentation flag indicating if the curve should be converted to a MontgomeryRepresentation + /// \sa ModularArithmetic, MontgomeryRepresentation ECP(const ECP &ecp, bool convertToMontgomeryRepresentation = false); - //! \brief Construct an ECP - //! \param modulus the prime modulus - //! \param a Field::Element - //! \param b Field::Element + /// \brief Construct an ECP + /// \param modulus the prime modulus + /// \param a Field::Element + /// \param b Field::Element ECP(const Integer &modulus, const FieldElement &a, const FieldElement &b) : m_fieldPtr(new Field(modulus)), m_a(a.IsNegative() ? modulus+a : a), m_b(b) {} - //! \brief Construct an ECP from BER encoded parameters - //! \param bt BufferedTransformation derived object - //! \details This constructor will decode and extract the the fields fieldID and curve of the sequence ECParameters + /// \brief Construct an ECP from BER encoded parameters + /// \param bt BufferedTransformation derived object + /// \details This constructor will decode and extract the the fields fieldID and curve of the sequence ECParameters ECP(BufferedTransformation &bt); - //! \brief Encode the fields fieldID and curve of the sequence ECParameters - //! \param bt BufferedTransformation derived object + /// \brief Encode the fields fieldID and curve of the sequence ECParameters + /// \param bt BufferedTransformation derived object void DEREncode(BufferedTransformation &bt) const; bool Equal(const Point &P, const Point &Q) const; @@ -104,16 +104,16 @@ private: CRYPTOPP_DLL_TEMPLATE_CLASS DL_FixedBasePrecomputationImpl; CRYPTOPP_DLL_TEMPLATE_CLASS DL_GroupPrecomputation; -//! \class EcPrecomputation -//! \brief Elliptic Curve precomputation -//! \tparam EC elliptic curve field +/// \class EcPrecomputation +/// \brief Elliptic Curve precomputation +/// \tparam EC elliptic curve field template class EcPrecomputation; -//! \class EcPrecomputation -//! \brief ECP precomputation specialization -//! \details Implementation of DL_GroupPrecomputation with input and output -//! conversions for Montgomery modular multiplication. -//! \sa DL_GroupPrecomputation, ModularArithmetic, MontgomeryRepresentation +/// \class EcPrecomputation +/// \brief ECP precomputation specialization +/// \details Implementation of DL_GroupPrecomputation with input and output +/// conversions for Montgomery modular multiplication. +/// \sa DL_GroupPrecomputation, ModularArithmetic, MontgomeryRepresentation template<> class EcPrecomputation : public DL_GroupPrecomputation { public: diff --git a/ecpoint.h b/ecpoint.h index 57f9f55a..5b726e4c 100644 --- a/ecpoint.h +++ b/ecpoint.h @@ -1,9 +1,9 @@ // ecpoint.h - written and placed in the public domain by Jeffrey Walton // Data structures moved from ecp.h and ec2n.h. Added EncodedPoint interface -//! \file ecpoint.h -//! \brief Classes for Elliptic Curve points -//! \since Crypto++ 6.0 +/// \file ecpoint.h +/// \brief Classes for Elliptic Curve points +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_ECPOINT_H #define CRYPTOPP_ECPOINT_H @@ -15,31 +15,31 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ECPPoint -//! \brief Elliptical Curve Point over GF(p), where p is prime -//! \since Crypto++ 2.0 +/// \class ECPPoint +/// \brief Elliptical Curve Point over GF(p), where p is prime +/// \since Crypto++ 2.0 struct CRYPTOPP_DLL ECPPoint { virtual ~ECPPoint() {} - //! \brief Construct an ECPPoint - //! \details identity is set to true + /// \brief Construct an ECPPoint + /// \details identity is set to true ECPPoint() : identity(true) {} - //! \brief Construct an ECPPoint from coordinates - //! \details identity is set to false + /// \brief Construct an ECPPoint from coordinates + /// \details identity is set to false ECPPoint(const Integer &x, const Integer &y) : x(x), y(y), identity(false) {} - //! \brief Tests points for equality - //! \param t the other point - //! \returns true if the points are equal, false otherwise + /// \brief Tests points for equality + /// \param t the other point + /// \returns true if the points are equal, false otherwise bool operator==(const ECPPoint &t) const {return (identity && t.identity) || (!identity && !t.identity && x==t.x && y==t.y);} - //! \brief Tests points for ordering - //! \param t the other point - //! \returns true if this point is less than other, false otherwise + /// \brief Tests points for ordering + /// \param t the other point + /// \returns true if this point is less than other, false otherwise bool operator< (const ECPPoint &t) const {return identity ? !t.identity : (!t.identity && (x; -//! \class EC2NPoint -//! \brief Elliptical Curve Point over GF(2^n) -//! \since Crypto++ 2.0 +/// \class EC2NPoint +/// \brief Elliptical Curve Point over GF(2^n) +/// \since Crypto++ 2.0 struct CRYPTOPP_DLL EC2NPoint { virtual ~EC2NPoint() {} - //! \brief Construct an EC2NPoint - //! \details identity is set to true + /// \brief Construct an EC2NPoint + /// \details identity is set to true EC2NPoint() : identity(true) {} - //! \brief Construct an EC2NPoint from coordinates - //! \details identity is set to false + /// \brief Construct an EC2NPoint from coordinates + /// \details identity is set to false EC2NPoint(const PolynomialMod2 &x, const PolynomialMod2 &y) : x(x), y(y), identity(false) {} - //! \brief Tests points for equality - //! \param t the other point - //! \returns true if the points are equal, false otherwise + /// \brief Tests points for equality + /// \param t the other point + /// \returns true if the points are equal, false otherwise bool operator==(const EC2NPoint &t) const {return (identity && t.identity) || (!identity && !t.identity && x==t.x && y==t.y);} - //! \brief Tests points for ordering - //! \param t the other point - //! \returns true if this point is less than other, false otherwise + /// \brief Tests points for ordering + /// \param t the other point + /// \returns true if this point is less than other, false otherwise bool operator< (const EC2NPoint &t) const {return identity ? !t.identity : (!t.identity && (x; -//! \class EncodedPoint -//! \brief Abstract class for encoding and decoding ellicptic curve points -//! \tparam Point ellicptic curve point -//! \details EncodedPoint is an interface for encoding and decoding elliptic curve points. -//! The template parameter Point should be a class like ECP or EC2N. -//! \since Crypto++ 6.0 +/// \class EncodedPoint +/// \brief Abstract class for encoding and decoding ellicptic curve points +/// \tparam Point ellicptic curve point +/// \details EncodedPoint is an interface for encoding and decoding elliptic curve points. +/// The template parameter Point should be a class like ECP or EC2N. +/// \since Crypto++ 6.0 template class EncodedPoint { public: virtual ~EncodedPoint() {} - //! \brief Decodes an elliptic curve point - //! \param P point which is decoded - //! \param bt source BufferedTransformation - //! \param len number of bytes to read from the BufferedTransformation - //! \returns true if a point was decoded, false otherwise + /// \brief Decodes an elliptic curve point + /// \param P point which is decoded + /// \param bt source BufferedTransformation + /// \param len number of bytes to read from the BufferedTransformation + /// \returns true if a point was decoded, false otherwise virtual bool DecodePoint(Point &P, BufferedTransformation &bt, size_t len) const =0; - //! \brief Decodes an elliptic curve point - //! \param P point which is decoded - //! \param encodedPoint byte array with the encoded point - //! \param len the size of the array - //! \returns true if a point was decoded, false otherwise + /// \brief Decodes an elliptic curve point + /// \param P point which is decoded + /// \param encodedPoint byte array with the encoded point + /// \param len the size of the array + /// \returns true if a point was decoded, false otherwise virtual bool DecodePoint(Point &P, const byte *encodedPoint, size_t len) const =0; - //! \brief Verifies points on elliptic curve - //! \param P point to verify - //! \returns true if the point is valid, false otherwise + /// \brief Verifies points on elliptic curve + /// \param P point to verify + /// \returns true if the point is valid, false otherwise virtual bool VerifyPoint(const Point &P) const =0; - //! \brief Determines encoded point size - //! \param compressed flag indicating if the point is compressed - //! \returns the minimum number of bytes required to encode the point + /// \brief Determines encoded point size + /// \param compressed flag indicating if the point is compressed + /// \returns the minimum number of bytes required to encode the point virtual unsigned int EncodedPointSize(bool compressed = false) const =0; - //! \brief Encodes an elliptic curve point - //! \param P point which is decoded - //! \param encodedPoint byte array for the encoded point - //! \param compressed flag indicating if the point is compressed - //! \details encodedPoint must be at least EncodedPointSize() in length + /// \brief Encodes an elliptic curve point + /// \param P point which is decoded + /// \param encodedPoint byte array for the encoded point + /// \param compressed flag indicating if the point is compressed + /// \details encodedPoint must be at least EncodedPointSize() in length virtual void EncodePoint(byte *encodedPoint, const Point &P, bool compressed) const =0; - //! \brief Encodes an elliptic curve point - //! \param bt target BufferedTransformation - //! \param P point which is encoded - //! \param compressed flag indicating if the point is compressed + /// \brief Encodes an elliptic curve point + /// \param bt target BufferedTransformation + /// \param P point which is encoded + /// \param compressed flag indicating if the point is compressed virtual void EncodePoint(BufferedTransformation &bt, const Point &P, bool compressed) const =0; - //! \brief BER Decodes an elliptic curve point - //! \param bt source BufferedTransformation - //! \returns the decoded elliptic curve point + /// \brief BER Decodes an elliptic curve point + /// \param bt source BufferedTransformation + /// \returns the decoded elliptic curve point virtual Point BERDecodePoint(BufferedTransformation &bt) const =0; - //! \brief DER Encodes an elliptic curve point - //! \param bt target BufferedTransformation - //! \param P point which is encoded - //! \param compressed flag indicating if the point is compressed + /// \brief DER Encodes an elliptic curve point + /// \param bt target BufferedTransformation + /// \param P point which is encoded + /// \param compressed flag indicating if the point is compressed virtual void DEREncodePoint(BufferedTransformation &bt, const Point &P, bool compressed) const =0; }; diff --git a/elgamal.h b/elgamal.h index 1b7906c8..79344b62 100644 --- a/elgamal.h +++ b/elgamal.h @@ -1,7 +1,7 @@ // elgamal.h - originally written and placed in the public domain by Wei Dai -//! \file elgamal.h -//! \brief Classes and functions for ElGamal key agreement and encryption schemes +/// \file elgamal.h +/// \brief Classes and functions for ElGamal key agreement and encryption schemes #ifndef CRYPTOPP_ELGAMAL_H #define CRYPTOPP_ELGAMAL_H @@ -16,9 +16,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ElGamalBase -//! \brief ElGamal key agreement and encryption schemes base class -//! \since Crypto++ 1.0 +/// \class ElGamalBase +/// \brief ElGamal key agreement and encryption schemes base class +/// \since Crypto++ 1.0 class CRYPTOPP_NO_VTABLE ElGamalBase : public DL_KeyAgreementAlgorithm_DH, public DL_KeyDerivationAlgorithm, public DL_SymmetricEncryptionAlgorithm @@ -93,9 +93,9 @@ public: virtual const DL_GroupParameters_GFP & GetGroupParameters() const =0; }; -//! \class ElGamalObjectImpl -//! \brief ElGamal key agreement and encryption schemes default implementation -//! \since Crypto++ 1.0 +/// \class ElGamalObjectImpl +/// \brief ElGamal key agreement and encryption schemes default implementation +/// \since Crypto++ 1.0 template class ElGamalObjectImpl : public DL_ObjectImplBase, public ElGamalBase { @@ -116,8 +116,8 @@ protected: const DL_SymmetricEncryptionAlgorithm & GetSymmetricEncryptionAlgorithm() const {return *this;} }; -//! \class ElGamalKeys -//! \brief ElGamal key agreement and encryption schemes keys +/// \class ElGamalKeys +/// \brief ElGamal key agreement and encryption schemes keys struct ElGamalKeys { typedef DL_CryptoKeys_GFP::GroupParameters GroupParameters; @@ -125,9 +125,9 @@ struct ElGamalKeys typedef DL_PublicKey_GFP_OldFormat PublicKey; }; -//! \class ElGamal -//! \brief ElGamal encryption scheme with non-standard padding -//! \since Crypto++ 1.0 +/// \class ElGamal +/// \brief ElGamal encryption scheme with non-standard padding +/// \since Crypto++ 1.0 struct ElGamal { typedef DL_CryptoSchemeOptions SchemeOptions; @@ -135,9 +135,9 @@ struct ElGamal CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "ElgamalEnc/Crypto++Padding";} typedef SchemeOptions::GroupParameters GroupParameters; - //! implements PK_Encryptor interface + /// implements PK_Encryptor interface typedef PK_FinalTemplate, SchemeOptions, SchemeOptions::PublicKey> > Encryptor; - //! implements PK_Decryptor interface + /// implements PK_Decryptor interface typedef PK_FinalTemplate, SchemeOptions, SchemeOptions::PrivateKey> > Decryptor; }; diff --git a/emsa2.h b/emsa2.h index 1ee4b76b..a156a75e 100644 --- a/emsa2.h +++ b/emsa2.h @@ -1,7 +1,7 @@ // emsa2.h - originally written and placed in the public domain by Wei Dai -//! \file emsa2.h -//! \brief Classes and functions for various padding schemes used in public key algorithms +/// \file emsa2.h +/// \brief Classes and functions for various padding schemes used in public key algorithms #ifndef CRYPTOPP_EMSA2_H #define CRYPTOPP_EMSA2_H @@ -57,7 +57,7 @@ CRYPTOPP_DLL_TEMPLATE_CLASS EMSA2HashId; CRYPTOPP_DLL_TEMPLATE_CLASS EMSA2HashId; #endif -//! _ +/// _ class CRYPTOPP_DLL EMSA2Pad : public EMSA2HashIdLookup { public: @@ -72,7 +72,7 @@ public: byte *representative, size_t representativeBitLength) const; }; -//! EMSA2, for use with RWSS and RSA_ISO +/// EMSA2, for use with RWSS and RSA_ISO /*! Only the following hash functions are supported by this signature standard: \dontinclude emsa2.h \skip EMSA2HashId can be instantiated diff --git a/eprecomp.h b/eprecomp.h index 57b99f1d..210f678c 100644 --- a/eprecomp.h +++ b/eprecomp.h @@ -1,7 +1,7 @@ // eprecomp.h - originally written and placed in the public domain by Wei Dai -//! \file eprecomp.h -//! \brief Classes for precomputation in a group +/// \file eprecomp.h +/// \brief Classes for precomputation in a group #ifndef CRYPTOPP_EPRECOMP_H #define CRYPTOPP_EPRECOMP_H diff --git a/esign.h b/esign.h index dcda42c4..7faeca55 100644 --- a/esign.h +++ b/esign.h @@ -1,8 +1,8 @@ // esign.h - originally written and placed in the public domain by Wei Dai -//! \file esign.h -//! \brief Classes providing ESIGN signature schemes as defined in IEEE P1363a -//! \since Crypto++ 5.0 +/// \file esign.h +/// \brief Classes providing ESIGN signature schemes as defined in IEEE P1363a +/// \since Crypto++ 5.0 #ifndef CRYPTOPP_ESIGN_H #define CRYPTOPP_ESIGN_H @@ -15,18 +15,18 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ESIGNFunction -//! \brief ESIGN trapdoor function using the public key -//! \since Crypto++ 5.0 +/// \class ESIGNFunction +/// \brief ESIGN trapdoor function using the public key +/// \since Crypto++ 5.0 class ESIGNFunction : public TrapdoorFunction, public ASN1CryptoMaterial { typedef ESIGNFunction ThisClass; public: - //! \brief Initialize a ESIGN public key with {n,e} - //! \param n the modulus - //! \param e the public exponent + /// \brief Initialize a ESIGN public key with {n,e} + /// \param n the modulus + /// \param e the public exponent void Initialize(const Integer &n, const Integer &e) {m_n = n; m_e = e;} @@ -58,30 +58,30 @@ protected: Integer m_n, m_e; }; -//! \class InvertibleESIGNFunction -//! \brief ESIGN trapdoor function using the private key -//! \since Crypto++ 5.0 +/// \class InvertibleESIGNFunction +/// \brief ESIGN trapdoor function using the private key +/// \since Crypto++ 5.0 class InvertibleESIGNFunction : public ESIGNFunction, public RandomizedTrapdoorFunctionInverse, public PrivateKey { typedef InvertibleESIGNFunction ThisClass; public: - //! \brief Initialize a ESIGN private key with {n,e,p,q} - //! \param n modulus - //! \param e public exponent - //! \param p first prime factor - //! \param q second prime factor - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize a ESIGN private key with {n,e,p,q} + /// \param n modulus + /// \param e public exponent + /// \param p first prime factor + /// \param q second prime factor + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const Integer &n, const Integer &e, const Integer &p, const Integer &q) {m_n = n; m_e = e; m_p = p; m_q = q;} - //! \brief Create a ESIGN private key - //! \param rng a RandomNumberGenerator derived class - //! \param modulusBits the size of the modulud, in bits - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a ESIGN private key + /// \param rng a RandomNumberGenerator derived class + /// \param modulusBits the size of the modulud, in bits + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits) {GenerateRandomWithKeySize(rng, modulusBits);} @@ -115,10 +115,10 @@ protected: Integer m_p, m_q; }; -//! \class EMSA5Pad -//! \brief EMSA5 padding method -//! \tparam T Mask Generation Function -//! \since Crypto++ 5.0 +/// \class EMSA5Pad +/// \brief EMSA5 padding method +/// \tparam T Mask Generation Function +/// \since Crypto++ 5.0 template class EMSA5Pad : public PK_DeterministicSignatureMessageEncodingMethod { @@ -142,9 +142,9 @@ public: } }; -//! \class P1363_EMSA5 -//! \brief EMSA5 padding method, for use with ESIGN -//! \since Crypto++ 5.0 +/// \class P1363_EMSA5 +/// \brief EMSA5 padding method, for use with ESIGN +/// \since Crypto++ 5.0 struct P1363_EMSA5 : public SignatureStandard { typedef EMSA5Pad SignatureMessageEncodingMethod; @@ -157,11 +157,11 @@ struct ESIGN_Keys typedef InvertibleESIGNFunction PrivateKey; }; -//! \class ESIGN -//! \brief ESIGN signature scheme, IEEE P1363a -//! \tparam H HashTransformation derived class -//! \tparam STANDARD Signature encoding method -//! \since Crypto++ 5.0 +/// \class ESIGN +/// \brief ESIGN signature scheme, IEEE P1363a +/// \tparam H HashTransformation derived class +/// \tparam STANDARD Signature encoding method +/// \since Crypto++ 5.0 template struct ESIGN : public TF_SS { diff --git a/factory.h b/factory.h index df69f0bb..ff2be1d9 100644 --- a/factory.h +++ b/factory.h @@ -1,7 +1,7 @@ // factory.h - originally written and placed in the public domain by Wei Dai -//! \file factory.h -//! \brief Classes and functions for registering and locating library objects +/// \file factory.h +/// \brief Classes and functions for registering and locating library objects #ifndef CRYPTOPP_OBJFACT_H #define CRYPTOPP_OBJFACT_H @@ -12,9 +12,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ObjectFactory -//! \brief Object factory interface for registering objects -//! \tparam AbstractClass Base class interface of the object +/// \class ObjectFactory +/// \brief Object factory interface for registering objects +/// \tparam AbstractClass Base class interface of the object template class ObjectFactory { @@ -23,10 +23,10 @@ public: virtual AbstractClass * CreateObject() const =0; }; -//! \class DefaultObjectFactory -//! \brief Object factory for registering objects -//! \tparam AbstractClass Base class interface of the object -//! \tparam ConcreteClass Class object +/// \class DefaultObjectFactory +/// \brief Object factory for registering objects +/// \tparam AbstractClass Base class interface of the object +/// \tparam ConcreteClass Class object template class DefaultObjectFactory : public ObjectFactory { @@ -37,10 +37,10 @@ public: } }; -//! \class ObjectFactoryRegistry -//! \brief Object factory registry -//! \tparam AbstractClass Base class interface of the object -//! \tparam instance unique identifier +/// \class ObjectFactoryRegistry +/// \brief Object factory registry +/// \tparam AbstractClass Base class interface of the object +/// \tparam instance unique identifier template class ObjectFactoryRegistry { @@ -105,11 +105,11 @@ ObjectFactoryRegistry & ObjectFactoryRegistry struct RegisterDefaultFactoryFor { @@ -122,13 +122,13 @@ struct RegisterDefaultFactoryFor } }; -//! \fn RegisterAsymmetricCipherDefaultFactories -//! \brief Register asymmetric ciphers -//! \tparam SchemeClass interface of the object under a scheme -//! \details Schemes include asymmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), -//! signature schemes (registers SchemeClass::Signer and SchemeClass::Verifier), -//! symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), -//! authenticated symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), etc. +/// \fn RegisterAsymmetricCipherDefaultFactories +/// \brief Register asymmetric ciphers +/// \tparam SchemeClass interface of the object under a scheme +/// \details Schemes include asymmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), +/// signature schemes (registers SchemeClass::Signer and SchemeClass::Verifier), +/// symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), +/// authenticated symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), etc. template void RegisterAsymmetricCipherDefaultFactories(const char *name=NULLPTR) { @@ -136,13 +136,13 @@ void RegisterAsymmetricCipherDefaultFactories(const char *name=NULLPTR) RegisterDefaultFactoryFor((const char *)name); } -//! \fn RegisterSignatureSchemeDefaultFactories -//! \brief Register signature schemes -//! \tparam SchemeClass interface of the object under a scheme -//! \details Schemes include asymmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), -//! signature schemes (registers SchemeClass::Signer and SchemeClass::Verifier), -//! symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), -//! authenticated symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), etc. +/// \fn RegisterSignatureSchemeDefaultFactories +/// \brief Register signature schemes +/// \tparam SchemeClass interface of the object under a scheme +/// \details Schemes include asymmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), +/// signature schemes (registers SchemeClass::Signer and SchemeClass::Verifier), +/// symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), +/// authenticated symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), etc. template void RegisterSignatureSchemeDefaultFactories(const char *name=NULLPTR) { @@ -150,13 +150,13 @@ void RegisterSignatureSchemeDefaultFactories(const char *name=NULLPTR) RegisterDefaultFactoryFor((const char *)name); } -//! \fn RegisterSymmetricCipherDefaultFactories -//! \brief Register symmetric ciphers -//! \tparam SchemeClass interface of the object under a scheme -//! \details Schemes include asymmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), -//! signature schemes (registers SchemeClass::Signer and SchemeClass::Verifier), -//! symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), -//! authenticated symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), etc. +/// \fn RegisterSymmetricCipherDefaultFactories +/// \brief Register symmetric ciphers +/// \tparam SchemeClass interface of the object under a scheme +/// \details Schemes include asymmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), +/// signature schemes (registers SchemeClass::Signer and SchemeClass::Verifier), +/// symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), +/// authenticated symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), etc. template void RegisterSymmetricCipherDefaultFactories(const char *name=NULLPTR) { @@ -164,13 +164,13 @@ void RegisterSymmetricCipherDefaultFactories(const char *name=NULLPTR) RegisterDefaultFactoryFor((const char *)name); } -//! \fn RegisterAuthenticatedSymmetricCipherDefaultFactories -//! \brief Register authenticated symmetric ciphers -//! \tparam SchemeClass interface of the object under a scheme -//! \details Schemes include asymmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), -//! signature schemes (registers SchemeClass::Signer and SchemeClass::Verifier), -//! symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), -//! authenticated symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), etc. +/// \fn RegisterAuthenticatedSymmetricCipherDefaultFactories +/// \brief Register authenticated symmetric ciphers +/// \tparam SchemeClass interface of the object under a scheme +/// \details Schemes include asymmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), +/// signature schemes (registers SchemeClass::Signer and SchemeClass::Verifier), +/// symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), +/// authenticated symmetric ciphers (registers SchemeClass::Encryptor and SchemeClass::Decryptor), etc. template void RegisterAuthenticatedSymmetricCipherDefaultFactories(const char *name=NULLPTR) { diff --git a/fhmqv.h b/fhmqv.h index 49120f02..38657ee8 100644 --- a/fhmqv.h +++ b/fhmqv.h @@ -4,9 +4,9 @@ #ifndef CRYPTOPP_FHMQV_H #define CRYPTOPP_FHMQV_H -//! \file fhmqv.h -//! \brief Classes for Fully Hashed Menezes-Qu-Vanstone key agreement in GF(p) -//! \since Crypto++ 5.6.4 +/// \file fhmqv.h +/// \brief Classes for Fully Hashed Menezes-Qu-Vanstone key agreement in GF(p) +/// \since Crypto++ 5.6.4 #include "gfpcrypt.h" #include "algebra.h" @@ -14,12 +14,12 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Fully Hashed Menezes-Qu-Vanstone in GF(p) -//! \details This implementation follows Augustin P. Sarr and Philippe Elbaz–Vincent, and Jean–Claude Bajard's -//! A Secure and Efficient Authenticated Diffie-Hellman Protocol. -//! Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C. -//! \sa MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain -//! \since Crypto++ 5.6.4 +/// \brief Fully Hashed Menezes-Qu-Vanstone in GF(p) +/// \details This implementation follows Augustin P. Sarr and Philippe Elbaz–Vincent, and Jean–Claude Bajard's +/// A Secure and Efficient Authenticated Diffie-Hellman Protocol. +/// Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C. +/// \sa MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain +/// \since Crypto++ 5.6.4 template class FHMQV_Domain : public AuthenticatedKeyAgreementDomain { @@ -66,14 +66,14 @@ public: CryptoParameters & AccessCryptoParameters(){return AccessAbstractGroupParameters();} - //! return length of agreed value produced + /// return length of agreed value produced unsigned int AgreedValueLength() const {return GetAbstractGroupParameters().GetEncodedElementSize(false);} - //! return length of static private keys in this domain + /// return length of static private keys in this domain unsigned int StaticPrivateKeyLength() const {return GetAbstractGroupParameters().GetSubgroupOrder().ByteCount();} - //! return length of static public keys in this domain + /// return length of static public keys in this domain unsigned int StaticPublicKeyLength() const{return GetAbstractGroupParameters().GetEncodedElementSize(true);} - //! generate static private key + /// generate static private key /*! \pre size of privateKey == PrivateStaticKeyLength() */ void GenerateStaticPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const { @@ -81,7 +81,7 @@ public: x.Encode(privateKey, StaticPrivateKeyLength()); } - //! generate static public key + /// generate static public key /*! \pre size of publicKey == PublicStaticKeyLength() */ void GenerateStaticPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const { @@ -95,7 +95,7 @@ public: unsigned int EphemeralPrivateKeyLength() const {return StaticPrivateKeyLength() + StaticPublicKeyLength();} unsigned int EphemeralPublicKeyLength() const{return StaticPublicKeyLength();} - //! return length of ephemeral private keys in this domain + /// return length of ephemeral private keys in this domain void GenerateEphemeralPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const { const DL_GroupParameters ¶ms = GetAbstractGroupParameters(); @@ -105,14 +105,14 @@ public: params.EncodeElement(true, y, privateKey+StaticPrivateKeyLength()); } - //! return length of ephemeral public keys in this domain + /// return length of ephemeral public keys in this domain void GenerateEphemeralPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const { CRYPTOPP_UNUSED(rng); memcpy(publicKey, privateKey+StaticPrivateKeyLength(), EphemeralPublicKeyLength()); } - //! derive agreed value from your private keys and couterparty's public keys, return false in case of failure + /// derive agreed value from your private keys and couterparty's public keys, return false in case of failure /*! \note The ephemeral public key will always be validated. If you have previously validated the static public key, use validateStaticOtherPublicKey=false to save time. \pre size of agreedValue == AgreedValueLength() @@ -289,12 +289,12 @@ private: KeyAgreementRole m_role; }; -//! \brief Fully Hashed Menezes-Qu-Vanstone in GF(p) -//! \details This implementation follows Augustin P. Sarr and Philippe Elbaz–Vincent, and Jean–Claude Bajard's -//! A Secure and Efficient Authenticated Diffie-Hellman Protocol. -//! Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C. -//! \sa FHMQV, MQV_Domain, HMQV_Domain, AuthenticatedKeyAgreementDomain -//! \since Crypto++ 5.6.4 +/// \brief Fully Hashed Menezes-Qu-Vanstone in GF(p) +/// \details This implementation follows Augustin P. Sarr and Philippe Elbaz–Vincent, and Jean–Claude Bajard's +/// A Secure and Efficient Authenticated Diffie-Hellman Protocol. +/// Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C. +/// \sa FHMQV, MQV_Domain, HMQV_Domain, AuthenticatedKeyAgreementDomain +/// \since Crypto++ 5.6.4 typedef FHMQV_Domain FHMQV; NAMESPACE_END diff --git a/files.h b/files.h index a2bf54b9..eff2b521 100644 --- a/files.h +++ b/files.h @@ -1,8 +1,8 @@ // files.h - originally written and placed in the public domain by Wei Dai -//! \file files.h -//! \brief Classes providing file-based library services -//! \since Crypto++ 1.0 +/// \file files.h +/// \brief Classes providing file-based library services +/// \since Crypto++ 1.0 #ifndef CRYPTOPP_FILES_H #define CRYPTOPP_FILES_H @@ -17,50 +17,50 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class FileStore -//! \brief Implementation of Store interface -//! \details file-based implementation of Store interface +/// \class FileStore +/// \brief Implementation of Store interface +/// \details file-based implementation of Store interface class CRYPTOPP_DLL FileStore : public Store, private FilterPutSpaceHelper, public NotCopyable { public: - //! \brief Exception thrown when file-based error is encountered + /// \brief Exception thrown when file-based error is encountered class Err : public Exception { public: Err(const std::string &s) : Exception(IO_ERROR, s) {} }; - //! \brief Exception thrown when file-based open error is encountered + /// \brief Exception thrown when file-based open error is encountered class OpenErr : public Err {public: OpenErr(const std::string &filename) : Err("FileStore: error opening file for reading: " + filename) {}}; - //! \brief Exception thrown when file-based read error is encountered + /// \brief Exception thrown when file-based read error is encountered class ReadErr : public Err {public: ReadErr() : Err("FileStore: error reading file") {}}; - //! \brief Construct a FileStore + /// \brief Construct a FileStore FileStore() : m_stream(NULLPTR), m_space(NULLPTR), m_len(0), m_waiting(0) {} - //! \brief Construct a FileStore - //! \param in an existing stream + /// \brief Construct a FileStore + /// \param in an existing stream FileStore(std::istream &in) : m_stream(NULLPTR), m_space(NULLPTR), m_len(0), m_waiting(0) {StoreInitialize(MakeParameters(Name::InputStreamPointer(), &in));} - //! \brief Construct a FileStore - //! \param filename the narrow name of the file to open + /// \brief Construct a FileStore + /// \param filename the narrow name of the file to open FileStore(const char *filename) : m_stream(NULLPTR), m_space(NULLPTR), m_len(0), m_waiting(0) {StoreInitialize(MakeParameters(Name::InputFileName(), filename ? filename : ""));} #if defined(CRYPTOPP_UNIX_AVAILABLE) || defined(CRYPTOPP_DOXYGEN_PROCESSING) || _MSC_VER >= 1400 - //! \brief Construct a FileStore - //! \param filename the Unicode name of the file to open - //! \details On non-Windows OS, this function assumes that setlocale() has been called. + /// \brief Construct a FileStore + /// \param filename the Unicode name of the file to open + /// \details On non-Windows OS, this function assumes that setlocale() has been called. FileStore(const wchar_t *filename) {StoreInitialize(MakeParameters(Name::InputFileNameWide(), filename));} #endif - //! \brief Retrieves the internal stream - //! \returns the internal stream pointer + /// \brief Retrieves the internal stream + /// \returns the internal stream pointer std::istream* GetStream() {return m_stream;} - //! \brief Retrieves the internal stream - //! \returns the internal stream pointer + /// \brief Retrieves the internal stream + /// \returns the internal stream pointer const std::istream* GetStream() const {return m_stream;} lword MaxRetrievable() const; @@ -78,9 +78,9 @@ private: bool m_waiting; }; -//! \class FileSource -//! \brief Implementation of Store interface -//! \details file-based implementation of Store interface +/// \class FileSource +/// \brief Implementation of Store interface +/// \details file-based implementation of Store interface class CRYPTOPP_DLL FileSource : public SourceTemplate { public: @@ -88,82 +88,82 @@ public: typedef FileStore::OpenErr OpenErr; typedef FileStore::ReadErr ReadErr; - //! \brief Construct a FileSource + /// \brief Construct a FileSource FileSource(BufferedTransformation *attachment = NULLPTR) : SourceTemplate(attachment) {} - //! \brief Construct a FileSource - //! \param in an existing stream - //! \param pumpAll flag indicating if source data should be pumped to its attached transformation - //! \param attachment an optional attached transformation + /// \brief Construct a FileSource + /// \param in an existing stream + /// \param pumpAll flag indicating if source data should be pumped to its attached transformation + /// \param attachment an optional attached transformation FileSource(std::istream &in, bool pumpAll, BufferedTransformation *attachment = NULLPTR) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters(Name::InputStreamPointer(), &in));} - //! \brief Construct a FileSource - //! \param filename the narrow name of the file to open - //! \param pumpAll flag indicating if source data should be pumped to its attached transformation - //! \param attachment an optional attached transformation - //! \param binary flag indicating if the file is binary + /// \brief Construct a FileSource + /// \param filename the narrow name of the file to open + /// \param pumpAll flag indicating if source data should be pumped to its attached transformation + /// \param attachment an optional attached transformation + /// \param binary flag indicating if the file is binary FileSource(const char *filename, bool pumpAll, BufferedTransformation *attachment = NULLPTR, bool binary=true) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters(Name::InputFileName(), filename)(Name::InputBinaryMode(), binary));} #if defined(CRYPTOPP_UNIX_AVAILABLE) || defined(CRYPTOPP_DOXYGEN_PROCESSING) || _MSC_VER >= 1400 - //! \brief Construct a FileSource - //! \param filename the Unicode name of the file to open - //! \param pumpAll flag indicating if source data should be pumped to its attached transformation - //! \param attachment an optional attached transformation - //! \param binary flag indicating if the file is binary - //! \details On non-Windows OS, this function assumes that setlocale() has been called. + /// \brief Construct a FileSource + /// \param filename the Unicode name of the file to open + /// \param pumpAll flag indicating if source data should be pumped to its attached transformation + /// \param attachment an optional attached transformation + /// \param binary flag indicating if the file is binary + /// \details On non-Windows OS, this function assumes that setlocale() has been called. FileSource(const wchar_t *filename, bool pumpAll, BufferedTransformation *attachment = NULLPTR, bool binary=true) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters(Name::InputFileNameWide(), filename)(Name::InputBinaryMode(), binary));} #endif - //! \brief Retrieves the internal stream - //! \returns the internal stream pointer + /// \brief Retrieves the internal stream + /// \returns the internal stream pointer std::istream* GetStream() {return m_store.GetStream();} }; -//! \class FileSink -//! \brief Implementation of Store interface -//! \details file-based implementation of Sink interface +/// \class FileSink +/// \brief Implementation of Store interface +/// \details file-based implementation of Sink interface class CRYPTOPP_DLL FileSink : public Sink, public NotCopyable { public: - //! \brief Exception thrown when file-based error is encountered + /// \brief Exception thrown when file-based error is encountered class Err : public Exception { public: Err(const std::string &s) : Exception(IO_ERROR, s) {} }; - //! \brief Exception thrown when file-based open error is encountered + /// \brief Exception thrown when file-based open error is encountered class OpenErr : public Err {public: OpenErr(const std::string &filename) : Err("FileSink: error opening file for writing: " + filename) {}}; - //! \brief Exception thrown when file-based write error is encountered + /// \brief Exception thrown when file-based write error is encountered class WriteErr : public Err {public: WriteErr() : Err("FileSink: error writing file") {}}; - //! \brief Construct a FileSink + /// \brief Construct a FileSink FileSink() : m_stream(NULLPTR) {} - //! \brief Construct a FileSink - //! \param out an existing stream + /// \brief Construct a FileSink + /// \param out an existing stream FileSink(std::ostream &out) {IsolatedInitialize(MakeParameters(Name::OutputStreamPointer(), &out));} - //! \brief Construct a FileSink - //! \param filename the narrow name of the file to open - //! \param binary flag indicating if the file is binary + /// \brief Construct a FileSink + /// \param filename the narrow name of the file to open + /// \param binary flag indicating if the file is binary FileSink(const char *filename, bool binary=true) {IsolatedInitialize(MakeParameters(Name::OutputFileName(), filename)(Name::OutputBinaryMode(), binary));} #if defined(CRYPTOPP_UNIX_AVAILABLE) || _MSC_VER >= 1400 - //! \brief Construct a FileSink - //! \param filename the Unicode name of the file to open - //! \details On non-Windows OS, this function assumes that setlocale() has been called. + /// \brief Construct a FileSink + /// \param filename the Unicode name of the file to open + /// \details On non-Windows OS, this function assumes that setlocale() has been called. FileSink(const wchar_t *filename, bool binary=true) {IsolatedInitialize(MakeParameters(Name::OutputFileNameWide(), filename)(Name::OutputBinaryMode(), binary));} #endif - //! \brief Retrieves the internal stream - //! \returns the internal stream pointer + /// \brief Retrieves the internal stream + /// \returns the internal stream pointer std::ostream* GetStream() {return m_stream;} void IsolatedInitialize(const NameValuePairs ¶meters); diff --git a/filters.h b/filters.h index e796022b..4b876c2c 100644 --- a/filters.h +++ b/filters.h @@ -1,7 +1,7 @@ // filters.h - originally written and placed in the public domain by Wei Dai -//! \file filters.h -//! \brief Implementation of BufferedTransformation's attachment interface. +/// \file filters.h +/// \brief Implementation of BufferedTransformation's attachment interface. #ifndef CRYPTOPP_FILTERS_H #define CRYPTOPP_FILTERS_H @@ -24,45 +24,45 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Filter -//! \brief Implementation of BufferedTransformation's attachment interface -//! \details Filter is a cornerstone of the Pipeline trinitiy. Data flows from -//! Sources, through Filters, and then terminates in Sinks. The difference -//! between a Source and Filter is a Source \a pumps data, while a Filter does -//! not. The difference between a Filter and a Sink is a Filter allows an -//! attached transformation, while a Sink does not. -//! \details See the discussion of BufferedTransformation in cryptlib.h for -//! more details. +/// \class Filter +/// \brief Implementation of BufferedTransformation's attachment interface +/// \details Filter is a cornerstone of the Pipeline trinitiy. Data flows from +/// Sources, through Filters, and then terminates in Sinks. The difference +/// between a Source and Filter is a Source \a pumps data, while a Filter does +/// not. The difference between a Filter and a Sink is a Filter allows an +/// attached transformation, while a Sink does not. +/// \details See the discussion of BufferedTransformation in cryptlib.h for +/// more details. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Filter : public BufferedTransformation, public NotCopyable { public: virtual ~Filter() {} - //! \name ATTACHMENT + /// \name ATTACHMENT //@{ - //! \brief Construct a Filter - //! \param attachment an optional attached transformation - //! \details attachment can be \p NULL. + /// \brief Construct a Filter + /// \param attachment an optional attached transformation + /// \details attachment can be \p NULL. Filter(BufferedTransformation *attachment = NULLPTR); - //! \brief Determine if attachable - //! \returns \p true if the object allows attached transformations, \p false otherwise. - //! \note Source and Filter offer attached transformations; while Sink does not. + /// \brief Determine if attachable + /// \returns \p true if the object allows attached transformations, \p false otherwise. + /// \note Source and Filter offer attached transformations; while Sink does not. bool Attachable() {return true;} - //! \brief Retrieve attached transformation - //! \returns pointer to a BufferedTransformation if there is an attached transformation, \p NULL otherwise. + /// \brief Retrieve attached transformation + /// \returns pointer to a BufferedTransformation if there is an attached transformation, \p NULL otherwise. BufferedTransformation *AttachedTransformation(); - //! \brief Retrieve attached transformation - //! \returns pointer to a BufferedTransformation if there is an attached transformation, \p NULL otherwise. + /// \brief Retrieve attached transformation + /// \returns pointer to a BufferedTransformation if there is an attached transformation, \p NULL otherwise. const BufferedTransformation *AttachedTransformation() const; - //! \brief Replace an attached transformation - //! \param newAttachment an optional attached transformation - //! \details newAttachment can be a single filter, a chain of filters or \p NULL. - //! Pass \p NULL to remove an existing BufferedTransformation or chain of filters + /// \brief Replace an attached transformation + /// \param newAttachment an optional attached transformation + /// \details newAttachment can be a single filter, a chain of filters or \p NULL. + /// Pass \p NULL to remove an existing BufferedTransformation or chain of filters void Detach(BufferedTransformation *newAttachment = NULLPTR); //@} @@ -85,66 +85,66 @@ protected: void PropagateInitialize(const NameValuePairs ¶meters, int propagation); - //! \brief Forward processed data on to attached transformation - //! \param outputSite unknown, system crash between keyboard and chair... - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one - //! \param blocking specifies whether the object should block when processing input - //! \param channel the channel to process the data - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + /// \brief Forward processed data on to attached transformation + /// \param outputSite unknown, system crash between keyboard and chair... + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one + /// \param blocking specifies whether the object should block when processing input + /// \param channel the channel to process the data + /// \returns the number of bytes that remain in the block (i.e., bytes not processed) size_t Output(int outputSite, const byte *inString, size_t length, int messageEnd, bool blocking, const std::string &channel=DEFAULT_CHANNEL); - //! \brief Output multiple bytes that may be modified by callee. - //! \param outputSite unknown, system crash between keyboard and chair... - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one - //! \param blocking specifies whether the object should block when processing input - //! \param channel the channel to process the data - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + /// \brief Output multiple bytes that may be modified by callee. + /// \param outputSite unknown, system crash between keyboard and chair... + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one + /// \param blocking specifies whether the object should block when processing input + /// \param channel the channel to process the data + /// \returns the number of bytes that remain in the block (i.e., bytes not processed) size_t OutputModifiable(int outputSite, byte *inString, size_t length, int messageEnd, bool blocking, const std::string &channel=DEFAULT_CHANNEL); - //! \brief Signals the end of messages to the object - //! \param outputSite unknown, system crash between keyboard and chair... - //! \param propagation the number of attached transformations the MessageEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \param channel the channel to process the data - //! \returns TODO - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. + /// \brief Signals the end of messages to the object + /// \param outputSite unknown, system crash between keyboard and chair... + /// \param propagation the number of attached transformations the MessageEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \param channel the channel to process the data + /// \returns TODO + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. bool OutputMessageEnd(int outputSite, int propagation, bool blocking, const std::string &channel=DEFAULT_CHANNEL); - //! \brief Flush buffered input and/or output, with signal propagation - //! \param outputSite unknown, system crash between keyboard and chair... - //! \param hardFlush is used to indicate whether all data should be flushed - //! \param propagation the number of attached transformations the Flush() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \param channel the channel to process the data - //! \returns TODO - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. - //! \note Hard flushes must be used with care. It means try to process and output everything, even if - //! there may not be enough data to complete the action. For example, hard flushing a HexDecoder - //! would cause an error if you do it after inputing an odd number of hex encoded characters. - //! \note For some types of filters, like ZlibDecompressor, hard flushes can only - //! be done at "synchronization points". These synchronization points are positions in the data - //! stream that are created by hard flushes on the corresponding reverse filters, in this - //! example ZlibCompressor. This is useful when zlib compressed data is moved across a - //! network in packets and compression state is preserved across packets, as in the SSH2 protocol. + /// \brief Flush buffered input and/or output, with signal propagation + /// \param outputSite unknown, system crash between keyboard and chair... + /// \param hardFlush is used to indicate whether all data should be flushed + /// \param propagation the number of attached transformations the Flush() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \param channel the channel to process the data + /// \returns TODO + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. + /// \note Hard flushes must be used with care. It means try to process and output everything, even if + /// there may not be enough data to complete the action. For example, hard flushing a HexDecoder + /// would cause an error if you do it after inputing an odd number of hex encoded characters. + /// \note For some types of filters, like ZlibDecompressor, hard flushes can only + /// be done at "synchronization points". These synchronization points are positions in the data + /// stream that are created by hard flushes on the corresponding reverse filters, in this + /// example ZlibCompressor. This is useful when zlib compressed data is moved across a + /// network in packets and compression state is preserved across packets, as in the SSH2 protocol. bool OutputFlush(int outputSite, bool hardFlush, int propagation, bool blocking, const std::string &channel=DEFAULT_CHANNEL); - //! \brief Marks the end of a series of messages, with signal propagation - //! \param outputSite unknown, system crash between keyboard and chair... - //! \param propagation the number of attached transformations the MessageSeriesEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \param channel the channel to process the data - //! \returns TODO - //! \details Each object that receives the signal will perform its processing, decrement - //! propagation, and then pass the signal on to attached transformations if the value is not 0. - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. - //! \note There should be a MessageEnd() immediately before MessageSeriesEnd(). + /// \brief Marks the end of a series of messages, with signal propagation + /// \param outputSite unknown, system crash between keyboard and chair... + /// \param propagation the number of attached transformations the MessageSeriesEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \param channel the channel to process the data + /// \returns TODO + /// \details Each object that receives the signal will perform its processing, decrement + /// propagation, and then pass the signal on to attached transformations if the value is not 0. + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. + /// \note There should be a MessageEnd() immediately before MessageSeriesEnd(). bool OutputMessageSeriesEnd(int outputSite, int propagation, bool blocking, const std::string &channel=DEFAULT_CHANNEL); private: @@ -155,25 +155,25 @@ protected: int m_continueAt; }; -//! \class FilterPutSpaceHelper -//! \brief Create a working space in a BufferedTransformation +/// \class FilterPutSpaceHelper +/// \brief Create a working space in a BufferedTransformation struct CRYPTOPP_DLL FilterPutSpaceHelper { virtual ~FilterPutSpaceHelper() {} - //! \brief Create a working space in a BufferedTransformation - //! \param target BufferedTransformation for the working space - //! \param channel channel for the working space - //! \param minSize minimum size of the allocation, in bytes - //! \param desiredSize preferred size of the allocation, in bytes - //! \param bufferSize actual size of the allocation, in bytes - //! \pre desiredSize >= minSize and bufferSize >= minSize. - //! \details \p bufferSize is an IN and OUT parameter. If HelpCreatePutSpace() returns a non-NULL value, then - //! bufferSize is valid and provides the size of the working space created for the caller. - //! \details Internally, HelpCreatePutSpace() calls \ref BufferedTransformation::ChannelCreatePutSpace - //! "ChannelCreatePutSpace()" using \p desiredSize. If the target returns \p desiredSize with a size less - //! than \p minSize (i.e., the request could not be fulfilled), then an internal SecByteBlock - //! called \p m_tempSpace is resized and used for the caller. + /// \brief Create a working space in a BufferedTransformation + /// \param target BufferedTransformation for the working space + /// \param channel channel for the working space + /// \param minSize minimum size of the allocation, in bytes + /// \param desiredSize preferred size of the allocation, in bytes + /// \param bufferSize actual size of the allocation, in bytes + /// \pre desiredSize >= minSize and bufferSize >= minSize. + /// \details \p bufferSize is an IN and OUT parameter. If HelpCreatePutSpace() returns a non-NULL value, then + /// bufferSize is valid and provides the size of the working space created for the caller. + /// \details Internally, HelpCreatePutSpace() calls \ref BufferedTransformation::ChannelCreatePutSpace + /// "ChannelCreatePutSpace()" using \p desiredSize. If the target returns \p desiredSize with a size less + /// than \p minSize (i.e., the request could not be fulfilled), then an internal SecByteBlock + /// called \p m_tempSpace is resized and used for the caller. byte *HelpCreatePutSpace(BufferedTransformation &target, const std::string &channel, size_t minSize, size_t desiredSize, size_t &bufferSize) { CRYPTOPP_ASSERT(desiredSize >= minSize && bufferSize >= minSize); @@ -192,62 +192,62 @@ struct CRYPTOPP_DLL FilterPutSpaceHelper return m_tempSpace.begin(); } - //! \brief Create a working space in a BufferedTransformation - //! \param target the BufferedTransformation for the working space - //! \param channel channel for the working space - //! \param minSize minimum size of the allocation, in bytes - //! \details Internally, the overload calls HelpCreatePutSpace(BufferedTransformation &target, const std::string &channel, size_t minSize, size_t desiredSize, size_t &bufferSize) using \p minSize for missing arguments. + /// \brief Create a working space in a BufferedTransformation + /// \param target the BufferedTransformation for the working space + /// \param channel channel for the working space + /// \param minSize minimum size of the allocation, in bytes + /// \details Internally, the overload calls HelpCreatePutSpace(BufferedTransformation &target, const std::string &channel, size_t minSize, size_t desiredSize, size_t &bufferSize) using \p minSize for missing arguments. byte *HelpCreatePutSpace(BufferedTransformation &target, const std::string &channel, size_t minSize) {return HelpCreatePutSpace(target, channel, minSize, minSize, minSize);} - //! \brief Create a working space in a BufferedTransformation - //! \param target the BufferedTransformation for the working space - //! \param channel channel for the working space - //! \param minSize minimum size of the allocation, in bytes - //! \param bufferSize the actual size of the allocation, in bytes - //! \details Internally, the overload calls HelpCreatePutSpace(BufferedTransformation &target, const std::string &channel, size_t minSize, size_t desiredSize, size_t &bufferSize) using \p minSize for missing arguments. + /// \brief Create a working space in a BufferedTransformation + /// \param target the BufferedTransformation for the working space + /// \param channel channel for the working space + /// \param minSize minimum size of the allocation, in bytes + /// \param bufferSize the actual size of the allocation, in bytes + /// \details Internally, the overload calls HelpCreatePutSpace(BufferedTransformation &target, const std::string &channel, size_t minSize, size_t desiredSize, size_t &bufferSize) using \p minSize for missing arguments. byte *HelpCreatePutSpace(BufferedTransformation &target, const std::string &channel, size_t minSize, size_t bufferSize) {return HelpCreatePutSpace(target, channel, minSize, minSize, bufferSize);} - //! \brief Temporay working space + /// \brief Temporay working space SecByteBlock m_tempSpace; }; -//! \class MeterFilter -//! \brief Measure how many bytes and messages pass through the filter -//! \details measure how many bytes and messages pass through the filter. The filter also serves as valve by -//! maintaining a list of ranges to skip during processing. +/// \class MeterFilter +/// \brief Measure how many bytes and messages pass through the filter +/// \details measure how many bytes and messages pass through the filter. The filter also serves as valve by +/// maintaining a list of ranges to skip during processing. class CRYPTOPP_DLL MeterFilter : public Bufferless { public: virtual ~MeterFilter() {} - //! \brief Construct a MeterFilter - //! \param attachment an optional attached transformation - //! \param transparent flag indicating if the filter should function transparently - //! \details \p attachment can be \p NULL. The filter is transparent by default. If the filter is - //! transparent, then PutMaybeModifiable() does not process a request and always returns 0. + /// \brief Construct a MeterFilter + /// \param attachment an optional attached transformation + /// \param transparent flag indicating if the filter should function transparently + /// \details \p attachment can be \p NULL. The filter is transparent by default. If the filter is + /// transparent, then PutMaybeModifiable() does not process a request and always returns 0. MeterFilter(BufferedTransformation *attachment=NULLPTR, bool transparent=true) : m_transparent(transparent), m_currentMessageBytes(0), m_totalBytes(0) , m_currentSeriesMessages(0), m_totalMessages(0), m_totalMessageSeries(0) , m_begin(NULLPTR), m_length(0) {Detach(attachment); ResetMeter();} - //! \brief Set or change the transparent mode of this object - //! \param transparent the new transparent mode + /// \brief Set or change the transparent mode of this object + /// \param transparent the new transparent mode void SetTransparent(bool transparent) {m_transparent = transparent;} - //! \brief Adds a range to skip during processing - //! \param message the message to apply the range - //! \param position the 0-based index in the current stream - //! \param size the length of the range - //! \param sortNow flag indicating whether the range should be sorted - //! \details Internally, MeterFilter maitains a deque of ranges to skip. As messages are processed, - //! ranges of bytes are skipped according to the list of ranges. + /// \brief Adds a range to skip during processing + /// \param message the message to apply the range + /// \param position the 0-based index in the current stream + /// \param size the length of the range + /// \param sortNow flag indicating whether the range should be sorted + /// \details Internally, MeterFilter maitains a deque of ranges to skip. As messages are processed, + /// ranges of bytes are skipped according to the list of ranges. void AddRangeToSkip(unsigned int message, lword position, lword size, bool sortNow = true); - //! \brief Resets the meter - //! \details ResetMeter() reinitializes the meter by setting counters to 0 and removing previous - //! skip ranges. + /// \brief Resets the meter + /// \details ResetMeter() reinitializes the meter by setting counters to 0 and removing previous + /// skip ranges. void ResetMeter(); void IsolatedInitialize(const NameValuePairs ¶meters) @@ -285,50 +285,50 @@ private: size_t m_length; }; -//! \class TransparentFilter -//! \brief A transparent MeterFilter -//! \sa MeterFilter, OpaqueFilter +/// \class TransparentFilter +/// \brief A transparent MeterFilter +/// \sa MeterFilter, OpaqueFilter class CRYPTOPP_DLL TransparentFilter : public MeterFilter { public: - //! \brief Construct a TransparentFilter - //! \param attachment an optional attached transformation + /// \brief Construct a TransparentFilter + /// \param attachment an optional attached transformation TransparentFilter(BufferedTransformation *attachment=NULLPTR) : MeterFilter(attachment, true) {} }; -//! \class OpaqueFilter -//! \brief A non-transparent MeterFilter -//! \sa MeterFilter, TransparentFilter +/// \class OpaqueFilter +/// \brief A non-transparent MeterFilter +/// \sa MeterFilter, TransparentFilter class CRYPTOPP_DLL OpaqueFilter : public MeterFilter { public: - //! \brief Construct an OpaqueFilter - //! \param attachment an optional attached transformation + /// \brief Construct an OpaqueFilter + /// \param attachment an optional attached transformation OpaqueFilter(BufferedTransformation *attachment=NULLPTR) : MeterFilter(attachment, false) {} }; -//! \class FilterWithBufferedInput -//! \brief Divides an input stream into discrete blocks -//! \details FilterWithBufferedInput divides the input stream into a first block, a number of -//! middle blocks, and a last block. First and last blocks are optional, and middle blocks may -//! be a stream instead (i.e. blockSize == 1). -//! \sa AuthenticatedEncryptionFilter, AuthenticatedDecryptionFilter, HashVerificationFilter, -//! SignatureVerificationFilter, StreamTransformationFilter +/// \class FilterWithBufferedInput +/// \brief Divides an input stream into discrete blocks +/// \details FilterWithBufferedInput divides the input stream into a first block, a number of +/// middle blocks, and a last block. First and last blocks are optional, and middle blocks may +/// be a stream instead (i.e. blockSize == 1). +/// \sa AuthenticatedEncryptionFilter, AuthenticatedDecryptionFilter, HashVerificationFilter, +/// SignatureVerificationFilter, StreamTransformationFilter class CRYPTOPP_DLL FilterWithBufferedInput : public Filter { public: virtual ~FilterWithBufferedInput() {} - //! \brief Construct a FilterWithBufferedInput with an attached transformation - //! \param attachment an attached transformation + /// \brief Construct a FilterWithBufferedInput with an attached transformation + /// \param attachment an attached transformation FilterWithBufferedInput(BufferedTransformation *attachment); - //! \brief Construct a FilterWithBufferedInput with an attached transformation - //! \param firstSize the size of the first block - //! \param blockSize the size of middle blocks - //! \param lastSize the size of the last block - //! \param attachment an attached transformation - //! \details \p firstSize and \p lastSize may be 0. \p blockSize must be at least 1. + /// \brief Construct a FilterWithBufferedInput with an attached transformation + /// \param firstSize the size of the first block + /// \param blockSize the size of middle blocks + /// \param lastSize the size of the last block + /// \param attachment an attached transformation + /// \details \p firstSize and \p lastSize may be 0. \p blockSize must be at least 1. FilterWithBufferedInput(size_t firstSize, size_t blockSize, size_t lastSize, BufferedTransformation *attachment); void IsolatedInitialize(const NameValuePairs ¶meters); @@ -342,16 +342,16 @@ public: return PutMaybeModifiable(inString, length, messageEnd, blocking, true); } - //! \brief Flushes data buffered by this object, without signal propagation - //! \param hardFlush indicates whether all data should be flushed - //! \param blocking specifies whether the object should block when processing input - //! \details IsolatedFlush() calls ForceNextPut() if hardFlush is true - //! \note hardFlush must be used with care + /// \brief Flushes data buffered by this object, without signal propagation + /// \param hardFlush indicates whether all data should be flushed + /// \param blocking specifies whether the object should block when processing input + /// \details IsolatedFlush() calls ForceNextPut() if hardFlush is true + /// \note hardFlush must be used with care bool IsolatedFlush(bool hardFlush, bool blocking); - //! \brief Flushes data buffered by this object - //! \details The input buffer may contain more than blockSize bytes if lastSize != 0. - //! ForceNextPut() forces a call to NextPut() if this is the case. + /// \brief Flushes data buffered by this object + /// \details The input buffer may contain more than blockSize bytes if lastSize != 0. + /// ForceNextPut() forces a call to NextPut() if this is the case. void ForceNextPut(); protected: @@ -377,16 +377,16 @@ protected: // Same as NextPutMultiple(), but inString can be modified virtual void NextPutModifiable(byte *inString, size_t length) {NextPutMultiple(inString, length);} - //! \brief Input the last block of data - //! \param inString the input byte buffer - //! \param length the size of the input buffer, in bytes - //! \details LastPut() processes the last block of data and signals attached filters to do the same. - //! LastPut() is always called. The pseudo algorithm for the logic is: - //! 
-	//!     if totalLength < firstSize then length == totalLength
-	//!     else if totalLength <= firstSize+lastSize then length == totalLength-firstSize
-	//!     else lastSize <= length < lastSize+blockSize
-	//!
+ /// \brief Input the last block of data + /// \param inString the input byte buffer + /// \param length the size of the input buffer, in bytes + /// \details LastPut() processes the last block of data and signals attached filters to do the same. + /// LastPut() is always called. The pseudo algorithm for the logic is: + /// 
+	///     if totalLength < firstSize then length == totalLength
+	///     else if totalLength <= firstSize+lastSize then length == totalLength-firstSize
+	///     else lastSize <= length < lastSize+blockSize
+	///
virtual void LastPut(const byte *inString, size_t length) =0; virtual void FlushDerived() {} @@ -425,18 +425,18 @@ protected: BlockQueue m_queue; }; -//! \class FilterWithInputQueue -//! \brief A filter that buffers input using a ByteQueue -//! \details FilterWithInputQueue will buffer input using a ByteQueue. When the filter receives -//! a \ref BufferedTransformation::MessageEnd() "MessageEnd()" signal it will pass the data -//! on to its attached transformation. +/// \class FilterWithInputQueue +/// \brief A filter that buffers input using a ByteQueue +/// \details FilterWithInputQueue will buffer input using a ByteQueue. When the filter receives +/// a \ref BufferedTransformation::MessageEnd() "MessageEnd()" signal it will pass the data +/// on to its attached transformation. class CRYPTOPP_DLL FilterWithInputQueue : public Filter { public: virtual ~FilterWithInputQueue() {} - //! \brief Construct a FilterWithInputQueue - //! \param attachment an optional attached transformation + /// \brief Construct a FilterWithInputQueue + /// \param attachment an optional attached transformation FilterWithInputQueue(BufferedTransformation *attachment=NULLPTR) : Filter(attachment) {} size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking) @@ -461,64 +461,64 @@ protected: ByteQueue m_inQueue; }; -//! \struct BlockPaddingSchemeDef -//! \brief Padding schemes used for block ciphers -//! \since Crypto++ 5.0 +/// \struct BlockPaddingSchemeDef +/// \brief Padding schemes used for block ciphers +/// \since Crypto++ 5.0 struct BlockPaddingSchemeDef { - //! \enum BlockPaddingScheme - //! \brief Padding schemes used for block ciphers. - //! \details DEFAULT_PADDING means PKCS_PADDING if cipher.MandatoryBlockSize() > 1 && - //! cipher.MinLastBlockSize() == 0, which holds for ECB or CBC mode. Otherwise, - //! NO_PADDING for modes like OFB, CFB, CTR, CBC-CTS. - //! \sa Block Cipher Padding for - //! additional details. - //! \since Crypto++ 5.0 + /// \enum BlockPaddingScheme + /// \brief Padding schemes used for block ciphers. + /// \details DEFAULT_PADDING means PKCS_PADDING if cipher.MandatoryBlockSize() > 1 && + /// cipher.MinLastBlockSize() == 0, which holds for ECB or CBC mode. Otherwise, + /// NO_PADDING for modes like OFB, CFB, CTR, CBC-CTS. + /// \sa Block Cipher Padding for + /// additional details. + /// \since Crypto++ 5.0 enum BlockPaddingScheme { - //! \brief No padding added to a block - //! \since Crypto++ 5.0 + /// \brief No padding added to a block + /// \since Crypto++ 5.0 NO_PADDING, - //! \brief 0's padding added to a block - //! \since Crypto++ 5.0 + /// \brief 0's padding added to a block + /// \since Crypto++ 5.0 ZEROS_PADDING, - //! \brief PKCS #5 padding added to a block - //! \since Crypto++ 5.0 + /// \brief PKCS #5 padding added to a block + /// \since Crypto++ 5.0 PKCS_PADDING, - //! \brief 1 and 0's padding added to a block - //! \since Crypto++ 5.0 + /// \brief 1 and 0's padding added to a block + /// \since Crypto++ 5.0 ONE_AND_ZEROS_PADDING, - //! \brief W3C padding added to a block - //! \sa XML - //! Encryption Syntax and Processing - //! \since Crypto++ 6.0 + /// \brief W3C padding added to a block + /// \sa XML + /// Encryption Syntax and Processing + /// \since Crypto++ 6.0 W3C_PADDING, - //! \brief Default padding scheme - //! \since Crypto++ 5.0 + /// \brief Default padding scheme + /// \since Crypto++ 5.0 DEFAULT_PADDING }; }; -//! \class StreamTransformationFilter -//! \brief Filter wrapper for StreamTransformation -//! \details StreamTransformationFilter() is a filter wrapper for StreamTransformation(). It is used when -//! pipelining data for stream ciphers and confidentiality-only block ciphers. The filter will optionally -//! handle padding and unpadding when needed. If you are using an authenticated encryption mode of operation, -//! then use AuthenticatedEncryptionFilter() and AuthenticatedDecryptionFilter() -//! \since Crypto++ 5.0 +/// \class StreamTransformationFilter +/// \brief Filter wrapper for StreamTransformation +/// \details StreamTransformationFilter() is a filter wrapper for StreamTransformation(). It is used when +/// pipelining data for stream ciphers and confidentiality-only block ciphers. The filter will optionally +/// handle padding and unpadding when needed. If you are using an authenticated encryption mode of operation, +/// then use AuthenticatedEncryptionFilter() and AuthenticatedDecryptionFilter() +/// \since Crypto++ 5.0 class CRYPTOPP_DLL StreamTransformationFilter : public FilterWithBufferedInput, public BlockPaddingSchemeDef, private FilterPutSpaceHelper { public: virtual ~StreamTransformationFilter() {} - //! \brief Construct a StreamTransformationFilter - //! \param c reference to a StreamTransformation - //! \param attachment an optional attached transformation - //! \param padding the \ref BlockPaddingSchemeDef "padding scheme" - //! \details This contructor creates a StreamTransformationFilter() for stream ciphers and - //! confidentiality-only block cipher modes of operation. If you are using an authenticated - //! encryption mode of operation, then use either AuthenticatedEncryptionFilter() or - //! AuthenticatedDecryptionFilter(). - //! \sa AuthenticatedEncryptionFilter() and AuthenticatedDecryptionFilter() + /// \brief Construct a StreamTransformationFilter + /// \param c reference to a StreamTransformation + /// \param attachment an optional attached transformation + /// \param padding the \ref BlockPaddingSchemeDef "padding scheme" + /// \details This contructor creates a StreamTransformationFilter() for stream ciphers and + /// confidentiality-only block cipher modes of operation. If you are using an authenticated + /// encryption mode of operation, then use either AuthenticatedEncryptionFilter() or + /// AuthenticatedDecryptionFilter(). + /// \sa AuthenticatedEncryptionFilter() and AuthenticatedDecryptionFilter() StreamTransformationFilter(StreamTransformation &c, BufferedTransformation *attachment = NULLPTR, BlockPaddingScheme padding = DEFAULT_PADDING); std::string AlgorithmName() const {return m_cipher.AlgorithmName();} @@ -528,13 +528,13 @@ protected: friend class AuthenticatedEncryptionFilter; friend class AuthenticatedDecryptionFilter; - //! \brief Construct a StreamTransformationFilter - //! \param c reference to a StreamTransformation - //! \param attachment an optional attached transformation - //! \param padding the \ref BlockPaddingSchemeDef "padding scheme" - //! \param authenticated flag indicating whether the filter should allow authenticated encryption schemes - //! \details This constructor is used for authenticated encryption mode of operation and by - //! AuthenticatedEncryptionFilter() and AuthenticatedDecryptionFilter(). + /// \brief Construct a StreamTransformationFilter + /// \param c reference to a StreamTransformation + /// \param attachment an optional attached transformation + /// \param padding the \ref BlockPaddingSchemeDef "padding scheme" + /// \param authenticated flag indicating whether the filter should allow authenticated encryption schemes + /// \details This constructor is used for authenticated encryption mode of operation and by + /// AuthenticatedEncryptionFilter() and AuthenticatedDecryptionFilter(). StreamTransformationFilter(StreamTransformation &c, BufferedTransformation *attachment, BlockPaddingScheme padding, bool authenticated); void InitializeDerivedAndReturnNewSizes(const NameValuePairs ¶meters, size_t &firstSize, size_t &blockSize, size_t &lastSize); @@ -553,21 +553,21 @@ protected: bool m_isSpecial; }; -//! \class HashFilter -//! \brief Filter wrapper for HashTransformation -//! \since Crypto++ 1.0 +/// \class HashFilter +/// \brief Filter wrapper for HashTransformation +/// \since Crypto++ 1.0 class CRYPTOPP_DLL HashFilter : public Bufferless, private FilterPutSpaceHelper { public: virtual ~HashFilter() {} - //! \brief Construct a HashFilter - //! \param hm reference to a HashTransformation - //! \param attachment an optional attached transformation - //! \param putMessage flag indicating whether the original message should be passed to an attached transformation - //! \param truncatedDigestSize the size of the digest - //! \param messagePutChannel the channel on which the message should be output - //! \param hashPutChannel the channel on which the digest should be output + /// \brief Construct a HashFilter + /// \param hm reference to a HashTransformation + /// \param attachment an optional attached transformation + /// \param putMessage flag indicating whether the original message should be passed to an attached transformation + /// \param truncatedDigestSize the size of the digest + /// \param messagePutChannel the channel on which the message should be output + /// \param hashPutChannel the channel on which the digest should be output HashFilter(HashTransformation &hm, BufferedTransformation *attachment = NULLPTR, bool putMessage=false, int truncatedDigestSize=-1, const std::string &messagePutChannel=DEFAULT_CHANNEL, const std::string &hashPutChannel=DEFAULT_CHANNEL); std::string AlgorithmName() const {return m_hashModule.AlgorithmName();} @@ -583,16 +583,16 @@ private: std::string m_messagePutChannel, m_hashPutChannel; }; -//! \class HashVerificationFilter -//! \brief Filter wrapper for HashTransformation -//! \since Crypto++ 4.0 +/// \class HashVerificationFilter +/// \brief Filter wrapper for HashTransformation +/// \since Crypto++ 4.0 class CRYPTOPP_DLL HashVerificationFilter : public FilterWithBufferedInput { public: virtual ~HashVerificationFilter() {} - //! \class HashVerificationFailed - //! \brief Exception thrown when a data integrity check failure is encountered + /// \class HashVerificationFailed + /// \brief Exception thrown when a data integrity check failure is encountered class HashVerificationFailed : public Exception { public: @@ -600,32 +600,32 @@ public: : Exception(DATA_INTEGRITY_CHECK_FAILED, "HashVerificationFilter: message hash or MAC not valid") {} }; - //! \enum Flags - //! \brief Flags controlling filter behavior. - //! \details The flags are a bitmask and can be OR'd together. + /// \enum Flags + /// \brief Flags controlling filter behavior. + /// \details The flags are a bitmask and can be OR'd together. enum Flags { - //! \brief Indicates the hash is at the end of the message (i.e., concatenation of message+hash) + /// \brief Indicates the hash is at the end of the message (i.e., concatenation of message+hash) HASH_AT_END=0, - //! \brief Indicates the hash is at the beginning of the message (i.e., concatenation of hash+message) + /// \brief Indicates the hash is at the beginning of the message (i.e., concatenation of hash+message) HASH_AT_BEGIN=1, - //! \brief Indicates the message should be passed to an attached transformation + /// \brief Indicates the message should be passed to an attached transformation PUT_MESSAGE=2, - //! \brief Indicates the hash should be passed to an attached transformation + /// \brief Indicates the hash should be passed to an attached transformation PUT_HASH=4, - //! \brief Indicates the result of the verification should be passed to an attached transformation + /// \brief Indicates the result of the verification should be passed to an attached transformation PUT_RESULT=8, - //! \brief Indicates the filter should throw a HashVerificationFailed if a failure is encountered + /// \brief Indicates the filter should throw a HashVerificationFailed if a failure is encountered THROW_EXCEPTION=16, - //! \brief Default flags using \p HASH_AT_BEGIN and \p PUT_RESULT + /// \brief Default flags using \p HASH_AT_BEGIN and \p PUT_RESULT DEFAULT_FLAGS = HASH_AT_BEGIN | PUT_RESULT }; - //! \brief Construct a HashVerificationFilter - //! \param hm reference to a HashTransformation - //! \param attachment an optional attached transformation - //! \param flags flags indicating behaviors for the filter - //! \param truncatedDigestSize the size of the digest - //! \details truncatedDigestSize = -1 indicates \ref HashTransformation::DigestSize() "DigestSize" should be used. + /// \brief Construct a HashVerificationFilter + /// \param hm reference to a HashTransformation + /// \param attachment an optional attached transformation + /// \param flags flags indicating behaviors for the filter + /// \param truncatedDigestSize the size of the digest + /// \details truncatedDigestSize = -1 indicates \ref HashTransformation::DigestSize() "DigestSize" should be used. HashVerificationFilter(HashTransformation &hm, BufferedTransformation *attachment = NULLPTR, word32 flags = DEFAULT_FLAGS, int truncatedDigestSize=-1); std::string AlgorithmName() const {return m_hashModule.AlgorithmName();} @@ -647,82 +647,82 @@ private: SecByteBlock m_expectedHash; }; -//! \class AuthenticatedEncryptionFilter -//! \brief Filter wrapper for encrypting with AuthenticatedSymmetricCipher -//! \details AuthenticatedEncryptionFilter() is a wrapper for encrypting with AuthenticatedSymmetricCipher(), -//! optionally handling padding/unpadding when needed. -//! \sa AuthenticatedDecryptionFilter, EAX, CCM, GCM, AuthenticatedSymmetricCipher -//! \since Crypto++ 5.6.0 +/// \class AuthenticatedEncryptionFilter +/// \brief Filter wrapper for encrypting with AuthenticatedSymmetricCipher +/// \details AuthenticatedEncryptionFilter() is a wrapper for encrypting with AuthenticatedSymmetricCipher(), +/// optionally handling padding/unpadding when needed. +/// \sa AuthenticatedDecryptionFilter, EAX, CCM, GCM, AuthenticatedSymmetricCipher +/// \since Crypto++ 5.6.0 class CRYPTOPP_DLL AuthenticatedEncryptionFilter : public StreamTransformationFilter { public: virtual ~AuthenticatedEncryptionFilter() {} - //! \brief Construct a AuthenticatedEncryptionFilter - //! \param c reference to a AuthenticatedSymmetricCipher - //! \param attachment an optional attached transformation - //! \param putAAD flag indicating whether the AAD should be passed to an attached transformation - //! \param truncatedDigestSize the size of the digest - //! \param macChannel the channel on which the MAC should be output - //! \param padding the \ref BlockPaddingSchemeDef "padding scheme" - //! \details truncatedDigestSize = -1 indicates \ref HashTransformation::DigestSize() "DigestSize" should be used. - //! \since Crypto++ 5.6.0 + /// \brief Construct a AuthenticatedEncryptionFilter + /// \param c reference to a AuthenticatedSymmetricCipher + /// \param attachment an optional attached transformation + /// \param putAAD flag indicating whether the AAD should be passed to an attached transformation + /// \param truncatedDigestSize the size of the digest + /// \param macChannel the channel on which the MAC should be output + /// \param padding the \ref BlockPaddingSchemeDef "padding scheme" + /// \details truncatedDigestSize = -1 indicates \ref HashTransformation::DigestSize() "DigestSize" should be used. + /// \since Crypto++ 5.6.0 AuthenticatedEncryptionFilter(AuthenticatedSymmetricCipher &c, BufferedTransformation *attachment = NULLPTR, bool putAAD=false, int truncatedDigestSize=-1, const std::string &macChannel=DEFAULT_CHANNEL, BlockPaddingScheme padding = DEFAULT_PADDING); void IsolatedInitialize(const NameValuePairs ¶meters); byte * ChannelCreatePutSpace(const std::string &channel, size_t &size); size_t ChannelPut2(const std::string &channel, const byte *begin, size_t length, int messageEnd, bool blocking); - //! \brief Input the last block of data - //! \param inString the input byte buffer - //! \param length the size of the input buffer, in bytes - //! \details LastPut() processes the last block of data and signals attached filters to do the same. - //! LastPut() is always called. The pseudo algorithm for the logic is: - //! 
-	//!     if totalLength < firstSize then length == totalLength
-	//!     else if totalLength <= firstSize+lastSize then length == totalLength-firstSize
-	//!     else lastSize <= length < lastSize+blockSize
-	//!
+ /// \brief Input the last block of data + /// \param inString the input byte buffer + /// \param length the size of the input buffer, in bytes + /// \details LastPut() processes the last block of data and signals attached filters to do the same. + /// LastPut() is always called. The pseudo algorithm for the logic is: + /// 
+	///     if totalLength < firstSize then length == totalLength
+	///     else if totalLength <= firstSize+lastSize then length == totalLength-firstSize
+	///     else lastSize <= length < lastSize+blockSize
+	///
void LastPut(const byte *inString, size_t length); protected: HashFilter m_hf; }; -//! \class AuthenticatedDecryptionFilter -//! \brief Filter wrapper for decrypting with AuthenticatedSymmetricCipher -//! \details AuthenticatedDecryptionFilter() is a wrapper for decrypting with AuthenticatedSymmetricCipher(), -//! optionally handling padding/unpadding when needed. -//! \sa AuthenticatedEncryptionFilter, EAX, CCM, GCM, AuthenticatedSymmetricCipher -//! \since Crypto++ 5.6.0 +/// \class AuthenticatedDecryptionFilter +/// \brief Filter wrapper for decrypting with AuthenticatedSymmetricCipher +/// \details AuthenticatedDecryptionFilter() is a wrapper for decrypting with AuthenticatedSymmetricCipher(), +/// optionally handling padding/unpadding when needed. +/// \sa AuthenticatedEncryptionFilter, EAX, CCM, GCM, AuthenticatedSymmetricCipher +/// \since Crypto++ 5.6.0 class CRYPTOPP_DLL AuthenticatedDecryptionFilter : public FilterWithBufferedInput, public BlockPaddingSchemeDef { public: - //! \enum Flags - //! \brief Flags controlling filter behavior. - //! \details The flags are a bitmask and can be OR'd together. + /// \enum Flags + /// \brief Flags controlling filter behavior. + /// \details The flags are a bitmask and can be OR'd together. enum Flags { - //! \brief Indicates the MAC is at the end of the message (i.e., concatenation of message+mac) + /// \brief Indicates the MAC is at the end of the message (i.e., concatenation of message+mac) MAC_AT_END=0, - //! \brief Indicates the MAC is at the beginning of the message (i.e., concatenation of mac+message) + /// \brief Indicates the MAC is at the beginning of the message (i.e., concatenation of mac+message) MAC_AT_BEGIN=1, - //! \brief Indicates the filter should throw a HashVerificationFailed if a failure is encountered + /// \brief Indicates the filter should throw a HashVerificationFailed if a failure is encountered THROW_EXCEPTION=16, - //! \brief Default flags using \p THROW_EXCEPTION + /// \brief Default flags using \p THROW_EXCEPTION DEFAULT_FLAGS = THROW_EXCEPTION }; virtual ~AuthenticatedDecryptionFilter() {} - //! \brief Construct a AuthenticatedDecryptionFilter - //! \param c reference to a AuthenticatedSymmetricCipher - //! \param attachment an optional attached transformation - //! \param flags flags indicating behaviors for the filter - //! \param truncatedDigestSize the size of the digest - //! \param padding the \ref BlockPaddingSchemeDef "padding scheme" - //! \details Additional authenticated data should be given in channel "AAD". - //! \details truncatedDigestSize = -1 indicates \ref HashTransformation::DigestSize() "DigestSize" should be used. - //! \since Crypto++ 5.6.0 + /// \brief Construct a AuthenticatedDecryptionFilter + /// \param c reference to a AuthenticatedSymmetricCipher + /// \param attachment an optional attached transformation + /// \param flags flags indicating behaviors for the filter + /// \param truncatedDigestSize the size of the digest + /// \param padding the \ref BlockPaddingSchemeDef "padding scheme" + /// \details Additional authenticated data should be given in channel "AAD". + /// \details truncatedDigestSize = -1 indicates \ref HashTransformation::DigestSize() "DigestSize" should be used. + /// \since Crypto++ 5.6.0 AuthenticatedDecryptionFilter(AuthenticatedSymmetricCipher &c, BufferedTransformation *attachment = NULLPTR, word32 flags = DEFAULT_FLAGS, int truncatedDigestSize=-1, BlockPaddingScheme padding = DEFAULT_PADDING); std::string AlgorithmName() const {return m_hashVerifier.AlgorithmName();} @@ -735,35 +735,35 @@ protected: void FirstPut(const byte *inString); void NextPutMultiple(const byte *inString, size_t length); - //! \brief Input the last block of data - //! \param inString the input byte buffer - //! \param length the size of the input buffer, in bytes - //! \details LastPut() processes the last block of data and signals attached filters to do the same. - //! LastPut() is always called. The pseudo algorithm for the logic is: - //! 
-	//!     if totalLength < firstSize then length == totalLength
-	//!     else if totalLength <= firstSize+lastSize then length == totalLength-firstSize
-	//!     else lastSize <= length < lastSize+blockSize
-	//!
+ /// \brief Input the last block of data + /// \param inString the input byte buffer + /// \param length the size of the input buffer, in bytes + /// \details LastPut() processes the last block of data and signals attached filters to do the same. + /// LastPut() is always called. The pseudo algorithm for the logic is: + /// 
+	///     if totalLength < firstSize then length == totalLength
+	///     else if totalLength <= firstSize+lastSize then length == totalLength-firstSize
+	///     else lastSize <= length < lastSize+blockSize
+	///
void LastPut(const byte *inString, size_t length); HashVerificationFilter m_hashVerifier; StreamTransformationFilter m_streamFilter; }; -//! \class SignerFilter -//! \brief Filter wrapper for PK_Signer -//! \since Crypto++ 4.0 +/// \class SignerFilter +/// \brief Filter wrapper for PK_Signer +/// \since Crypto++ 4.0 class CRYPTOPP_DLL SignerFilter : public Unflushable { public: virtual ~SignerFilter() {} - //! \brief Construct a SignerFilter - //! \param rng a RandomNumberGenerator derived class - //! \param signer a PK_Signer derived class - //! \param attachment an optional attached transformation - //! \param putMessage flag indicating whether the original message should be passed to an attached transformation + /// \brief Construct a SignerFilter + /// \param rng a RandomNumberGenerator derived class + /// \param signer a PK_Signer derived class + /// \param attachment an optional attached transformation + /// \param putMessage flag indicating whether the original message should be passed to an attached transformation SignerFilter(RandomNumberGenerator &rng, const PK_Signer &signer, BufferedTransformation *attachment = NULLPTR, bool putMessage=false) : m_rng(rng), m_signer(signer), m_messageAccumulator(signer.NewSignatureAccumulator(rng)), m_putMessage(putMessage) {Detach(attachment);} @@ -780,14 +780,14 @@ private: SecByteBlock m_buf; }; -//! \class SignatureVerificationFilter -//! \brief Filter wrapper for PK_Verifier -//! \details This filter was formerly named VerifierFilter. The name changed at Crypto++ 5.0. -//! \since Crypto++ 4.0 +/// \class SignatureVerificationFilter +/// \brief Filter wrapper for PK_Verifier +/// \details This filter was formerly named VerifierFilter. The name changed at Crypto++ 5.0. +/// \since Crypto++ 4.0 class CRYPTOPP_DLL SignatureVerificationFilter : public FilterWithBufferedInput { public: - //! \brief Exception thrown when an invalid signature is encountered + /// \brief Exception thrown when an invalid signature is encountered class SignatureVerificationFailed : public Exception { public: @@ -795,38 +795,38 @@ public: : Exception(DATA_INTEGRITY_CHECK_FAILED, "VerifierFilter: digital signature not valid") {} }; - //! \enum Flags - //! \brief Flags controlling filter behavior. - //! \details The flags are a bitmask and can be OR'd together. + /// \enum Flags + /// \brief Flags controlling filter behavior. + /// \details The flags are a bitmask and can be OR'd together. enum Flags { - //! \brief Indicates the signature is at the end of the message (i.e., concatenation of message+signature) + /// \brief Indicates the signature is at the end of the message (i.e., concatenation of message+signature) SIGNATURE_AT_END=0, - //! \brief Indicates the signature is at the beginning of the message (i.e., concatenation of signature+message) + /// \brief Indicates the signature is at the beginning of the message (i.e., concatenation of signature+message) SIGNATURE_AT_BEGIN=1, - //! \brief Indicates the message should be passed to an attached transformation + /// \brief Indicates the message should be passed to an attached transformation PUT_MESSAGE=2, - //! \brief Indicates the signature should be passed to an attached transformation + /// \brief Indicates the signature should be passed to an attached transformation PUT_SIGNATURE=4, - //! \brief Indicates the result of the verification should be passed to an attached transformation + /// \brief Indicates the result of the verification should be passed to an attached transformation PUT_RESULT=8, - //! \brief Indicates the filter should throw a HashVerificationFailed if a failure is encountered + /// \brief Indicates the filter should throw a HashVerificationFailed if a failure is encountered THROW_EXCEPTION=16, - //! \brief Default flags using \p SIGNATURE_AT_BEGIN and \p PUT_RESULT + /// \brief Default flags using \p SIGNATURE_AT_BEGIN and \p PUT_RESULT DEFAULT_FLAGS = SIGNATURE_AT_BEGIN | PUT_RESULT }; virtual ~SignatureVerificationFilter() {} - //! \brief Construct a SignatureVerificationFilter - //! \param verifier a PK_Verifier derived class - //! \param attachment an optional attached transformation - //! \param flags flags indicating behaviors for the filter + /// \brief Construct a SignatureVerificationFilter + /// \param verifier a PK_Verifier derived class + /// \param attachment an optional attached transformation + /// \param flags flags indicating behaviors for the filter SignatureVerificationFilter(const PK_Verifier &verifier, BufferedTransformation *attachment = NULLPTR, word32 flags = DEFAULT_FLAGS); std::string AlgorithmName() const {return m_verifier.AlgorithmName();} - //! \brief Retrieves the result of the last verification - //! \returns true if the signature on the previosus message was valid, false otherwise + /// \brief Retrieves the result of the last verification + /// \returns true if the signature on the previosus message was valid, false otherwise bool GetLastResult() const {return m_verified;} protected: @@ -843,42 +843,42 @@ private: bool m_verified; }; -//! \class Redirector -//! \brief Redirect input to another BufferedTransformation without owning it -//! \since Crypto++ 4.0 +/// \class Redirector +/// \brief Redirect input to another BufferedTransformation without owning it +/// \since Crypto++ 4.0 class CRYPTOPP_DLL Redirector : public CustomSignalPropagation { public: - //! \enum Behavior - //! \brief Controls signal propagation behavior + /// \enum Behavior + /// \brief Controls signal propagation behavior enum Behavior { - //! \brief Pass data only + /// \brief Pass data only DATA_ONLY = 0x00, - //! \brief Pass signals + /// \brief Pass signals PASS_SIGNALS = 0x01, - //! \brief Pass wait events + /// \brief Pass wait events PASS_WAIT_OBJECTS = 0x02, - //! \brief Pass everything - //! \details PASS_EVERYTHING is default + /// \brief Pass everything + /// \details PASS_EVERYTHING is default PASS_EVERYTHING = PASS_SIGNALS | PASS_WAIT_OBJECTS }; virtual ~Redirector() {} - //! \brief Construct a Redirector + /// \brief Construct a Redirector Redirector() : m_target(NULLPTR), m_behavior(PASS_EVERYTHING) {} - //! \brief Construct a Redirector - //! \param target the destination BufferedTransformation - //! \param behavior Behavior "flags" specifying signal propagation + /// \brief Construct a Redirector + /// \param target the destination BufferedTransformation + /// \param behavior Behavior "flags" specifying signal propagation Redirector(BufferedTransformation &target, Behavior behavior=PASS_EVERYTHING) : m_target(&target), m_behavior(behavior) {} - //! \brief Redirect input to another BufferedTransformation - //! \param target the destination BufferedTransformation + /// \brief Redirect input to another BufferedTransformation + /// \param target the destination BufferedTransformation void Redirect(BufferedTransformation &target) {m_target = ⌖} - //! \brief Stop redirecting input + /// \brief Stop redirecting input void StopRedirection() {m_target = NULLPTR;} Behavior GetBehavior() {return (Behavior) m_behavior;} @@ -938,25 +938,25 @@ private: word32 m_behavior; }; -//! \class OutputProxy -//! \brief Filter class that is a proxy for a sink -//! \details Used By ProxyFilter -//! \since Crypto++ 4.0 +/// \class OutputProxy +/// \brief Filter class that is a proxy for a sink +/// \details Used By ProxyFilter +/// \since Crypto++ 4.0 class CRYPTOPP_DLL OutputProxy : public CustomSignalPropagation { public: virtual ~OutputProxy() {} - //! \brief Construct an OutputProxy - //! \param owner the owning transformation - //! \param passSignal flag indicating if signals should be passed + /// \brief Construct an OutputProxy + /// \param owner the owning transformation + /// \param passSignal flag indicating if signals should be passed OutputProxy(BufferedTransformation &owner, bool passSignal) : m_owner(owner), m_passSignal(passSignal) {} - //! \brief Retrieve passSignal flag - //! \returns flag indicating if signals should be passed + /// \brief Retrieve passSignal flag + /// \returns flag indicating if signals should be passed bool GetPassSignal() const {return m_passSignal;} - //! \brief Set passSignal flag - //! \param passSignal flag indicating if signals should be passed + /// \brief Set passSignal flag + /// \param passSignal flag indicating if signals should be passed void SetPassSignal(bool passSignal) {m_passSignal = passSignal;} byte * CreatePutSpace(size_t &size) @@ -988,25 +988,25 @@ private: bool m_passSignal; }; -//! \class ProxyFilter -//! \brief Base class for Filter classes that are proxies for a chain of other filters -//! \since Crypto++ 4.0 +/// \class ProxyFilter +/// \brief Base class for Filter classes that are proxies for a chain of other filters +/// \since Crypto++ 4.0 class CRYPTOPP_DLL ProxyFilter : public FilterWithBufferedInput { public: virtual ~ProxyFilter() {} - //! \brief Construct a ProxyFilter - //! \param filter an output filter - //! \param firstSize the first Put size - //! \param lastSize the last Put size - //! \param attachment an attached transformation + /// \brief Construct a ProxyFilter + /// \param filter an output filter + /// \param firstSize the first Put size + /// \param lastSize the last Put size + /// \param attachment an attached transformation ProxyFilter(BufferedTransformation *filter, size_t firstSize, size_t lastSize, BufferedTransformation *attachment); bool IsolatedFlush(bool hardFlush, bool blocking); - //! \brief Sets the OutputProxy filter - //! \param filter an OutputProxy filter + /// \brief Sets the OutputProxy filter + /// \param filter an OutputProxy filter void SetFilter(Filter *filter); void NextPutMultiple(const byte *s, size_t len); void NextPutModifiable(byte *inString, size_t length); @@ -1015,80 +1015,80 @@ protected: member_ptr m_filter; }; -//! \class SimpleProxyFilter -//! \brief Proxy filter that doesn't modify the underlying filter's input or output -//! \since Crypto++ 5.0 +/// \class SimpleProxyFilter +/// \brief Proxy filter that doesn't modify the underlying filter's input or output +/// \since Crypto++ 5.0 class CRYPTOPP_DLL SimpleProxyFilter : public ProxyFilter { public: - //! \brief Construct a SimpleProxyFilter - //! \param filter an output filter - //! \param attachment an attached transformation + /// \brief Construct a SimpleProxyFilter + /// \param filter an output filter + /// \param attachment an attached transformation SimpleProxyFilter(BufferedTransformation *filter, BufferedTransformation *attachment) : ProxyFilter(filter, 0, 0, attachment) {} void FirstPut(const byte * inString) {CRYPTOPP_UNUSED(inString);} - //! \brief Input the last block of data - //! \param inString the input byte buffer - //! \param length the size of the input buffer, in bytes - //! \details LastPut() processes the last block of data and signals attached filters to do the same. - //! LastPut() is always called. The pseudo algorithm for the logic is: - //! 
-	//!     if totalLength < firstSize then length == totalLength
-	//!     else if totalLength <= firstSize+lastSize then length == totalLength-firstSize
-	//!     else lastSize <= length < lastSize+blockSize
-	//!
+ /// \brief Input the last block of data + /// \param inString the input byte buffer + /// \param length the size of the input buffer, in bytes + /// \details LastPut() processes the last block of data and signals attached filters to do the same. + /// LastPut() is always called. The pseudo algorithm for the logic is: + /// 
+	///     if totalLength < firstSize then length == totalLength
+	///     else if totalLength <= firstSize+lastSize then length == totalLength-firstSize
+	///     else lastSize <= length < lastSize+blockSize
+	///
void LastPut(const byte *inString, size_t length) {CRYPTOPP_UNUSED(inString), CRYPTOPP_UNUSED(length); m_filter->MessageEnd();} }; -//! \class PK_EncryptorFilter -//! \brief Filter wrapper for PK_Encryptor -//! \details PK_DecryptorFilter is a proxy for the filter created by PK_Encryptor::CreateEncryptionFilter. -//! This class provides symmetry with VerifierFilter. -//! \since Crypto++ 5.0 +/// \class PK_EncryptorFilter +/// \brief Filter wrapper for PK_Encryptor +/// \details PK_DecryptorFilter is a proxy for the filter created by PK_Encryptor::CreateEncryptionFilter. +/// This class provides symmetry with VerifierFilter. +/// \since Crypto++ 5.0 class CRYPTOPP_DLL PK_EncryptorFilter : public SimpleProxyFilter { public: - //! \brief Construct a PK_EncryptorFilter - //! \param rng a RandomNumberGenerator derived class - //! \param encryptor a PK_Encryptor derived class - //! \param attachment an optional attached transformation + /// \brief Construct a PK_EncryptorFilter + /// \param rng a RandomNumberGenerator derived class + /// \param encryptor a PK_Encryptor derived class + /// \param attachment an optional attached transformation PK_EncryptorFilter(RandomNumberGenerator &rng, const PK_Encryptor &encryptor, BufferedTransformation *attachment = NULLPTR) : SimpleProxyFilter(encryptor.CreateEncryptionFilter(rng), attachment) {} }; -//! \class PK_DecryptorFilter -//! \brief Filter wrapper for PK_Decryptor -//! \details PK_DecryptorFilter is a proxy for the filter created by PK_Decryptor::CreateDecryptionFilter. -//! This class provides symmetry with SignerFilter. -//! \since Crypto++ 5.0 +/// \class PK_DecryptorFilter +/// \brief Filter wrapper for PK_Decryptor +/// \details PK_DecryptorFilter is a proxy for the filter created by PK_Decryptor::CreateDecryptionFilter. +/// This class provides symmetry with SignerFilter. +/// \since Crypto++ 5.0 class CRYPTOPP_DLL PK_DecryptorFilter : public SimpleProxyFilter { public: - //! \brief Construct a PK_DecryptorFilter - //! \param rng a RandomNumberGenerator derived class - //! \param decryptor a PK_Decryptor derived class - //! \param attachment an optional attached transformation + /// \brief Construct a PK_DecryptorFilter + /// \param rng a RandomNumberGenerator derived class + /// \param decryptor a PK_Decryptor derived class + /// \param attachment an optional attached transformation PK_DecryptorFilter(RandomNumberGenerator &rng, const PK_Decryptor &decryptor, BufferedTransformation *attachment = NULLPTR) : SimpleProxyFilter(decryptor.CreateDecryptionFilter(rng), attachment) {} }; -//! \class StringSinkTemplate -//! \brief Append input to a string object -//! \tparam T std::basic_string type -//! \details StringSinkTemplate is a StringSinkTemplate typedef -//! \since Crypto++ 5.0 +/// \class StringSinkTemplate +/// \brief Append input to a string object +/// \tparam T std::basic_string type +/// \details StringSinkTemplate is a StringSinkTemplate typedef +/// \since Crypto++ 5.0 template class StringSinkTemplate : public Bufferless { public: virtual ~StringSinkTemplate() {} - //! \brief Construct a StringSinkTemplate - //! \param output std::basic_string type + /// \brief Construct a StringSinkTemplate + /// \param output std::basic_string type StringSinkTemplate(T &output) : m_output(&output) {CRYPTOPP_ASSERT(sizeof(output[0])==1);} @@ -1114,28 +1114,28 @@ private: T *m_output; }; -//! \class StringSink -//! \brief Append input to a string object -//! \details StringSink is a typedef for StringSinkTemplate. -//! \sa ArraySink, ArrayXorSink -//! \since Crypto++ 4.0 +/// \class StringSink +/// \brief Append input to a string object +/// \details StringSink is a typedef for StringSinkTemplate. +/// \sa ArraySink, ArrayXorSink +/// \since Crypto++ 4.0 DOCUMENTED_TYPEDEF(StringSinkTemplate, StringSink) CRYPTOPP_DLL_TEMPLATE_CLASS StringSinkTemplate; -//! \class RandomNumberSink -//! \brief Incorporates input into RNG as additional entropy -//! \since Crypto++ 4.0 +/// \class RandomNumberSink +/// \brief Incorporates input into RNG as additional entropy +/// \since Crypto++ 4.0 class RandomNumberSink : public Bufferless { public: virtual ~RandomNumberSink() {} - //! \brief Construct a RandomNumberSink + /// \brief Construct a RandomNumberSink RandomNumberSink() : m_rng(NULLPTR) {} - //! \brief Construct a RandomNumberSink - //! \param rng a RandomNumberGenerator derived class + /// \brief Construct a RandomNumberSink + /// \param rng a RandomNumberGenerator derived class RandomNumberSink(RandomNumberGenerator &rng) : m_rng(&rng) {} @@ -1146,37 +1146,37 @@ private: RandomNumberGenerator *m_rng; }; -//! \class ArraySink -//! \brief Copy input to a memory buffer -//! \details ArraySink wraps a fixed size buffer. The buffer is full once Put returns non-0. -//! When used in a pipleline, ArraySink silently discards input if the buffer is full. -//! AvailableSize() can be used to determine how much space remains in the buffer. -//! TotalPutLength() can be used to determine how many bytes were processed. -//! \sa StringSink, ArrayXorSink -//! \since Crypto++ 4.0 +/// \class ArraySink +/// \brief Copy input to a memory buffer +/// \details ArraySink wraps a fixed size buffer. The buffer is full once Put returns non-0. +/// When used in a pipleline, ArraySink silently discards input if the buffer is full. +/// AvailableSize() can be used to determine how much space remains in the buffer. +/// TotalPutLength() can be used to determine how many bytes were processed. +/// \sa StringSink, ArrayXorSink +/// \since Crypto++ 4.0 class CRYPTOPP_DLL ArraySink : public Bufferless { public: virtual ~ArraySink() {} - //! \brief Construct an ArraySink - //! \param parameters a set of NameValuePairs to initialize this object - //! \details Name::OutputBuffer() is a mandatory parameter using this constructor. + /// \brief Construct an ArraySink + /// \param parameters a set of NameValuePairs to initialize this object + /// \details Name::OutputBuffer() is a mandatory parameter using this constructor. ArraySink(const NameValuePairs ¶meters = g_nullNameValuePairs) : m_buf(NULLPTR), m_size(0), m_total(0) {IsolatedInitialize(parameters);} - //! \brief Construct an ArraySink - //! \param buf pointer to a memory buffer - //! \param size length of the memory buffer + /// \brief Construct an ArraySink + /// \param buf pointer to a memory buffer + /// \param size length of the memory buffer ArraySink(byte *buf, size_t size) : m_buf(buf), m_size(size), m_total(0) {} - //! \brief Provides the size remaining in the Sink - //! \returns size remaining in the Sink, in bytes + /// \brief Provides the size remaining in the Sink + /// \returns size remaining in the Sink, in bytes size_t AvailableSize() {return SaturatingSubtract(m_size, m_total);} - //! \brief Provides the number of bytes written to the Sink - //! \returns number of bytes written to the Sink, in bytes + /// \brief Provides the number of bytes written to the Sink + /// \returns number of bytes written to the Sink, in bytes lword TotalPutLength() {return m_total;} void IsolatedInitialize(const NameValuePairs ¶meters); @@ -1189,22 +1189,22 @@ protected: lword m_total; }; -//! \class ArrayXorSink -//! \brief Xor input to a memory buffer -//! \details ArrayXorSink wraps a fixed size buffer. The buffer is full once Put returns non-0. -//! When used in a pipleline, ArrayXorSink silently discards input if the buffer is full. -//! AvailableSize() can be used to determine how much space remains in the buffer. -//! TotalPutLength() can be used to determine how many bytes were processed. -//! \sa StringSink, ArraySink -//! \since Crypto++ 4.0 +/// \class ArrayXorSink +/// \brief Xor input to a memory buffer +/// \details ArrayXorSink wraps a fixed size buffer. The buffer is full once Put returns non-0. +/// When used in a pipleline, ArrayXorSink silently discards input if the buffer is full. +/// AvailableSize() can be used to determine how much space remains in the buffer. +/// TotalPutLength() can be used to determine how many bytes were processed. +/// \sa StringSink, ArraySink +/// \since Crypto++ 4.0 class CRYPTOPP_DLL ArrayXorSink : public ArraySink { public: virtual ~ArrayXorSink() {} - //! \brief Construct an ArrayXorSink - //! \param buf pointer to a memory buffer - //! \param size length of the memory buffer + /// \brief Construct an ArrayXorSink + /// \param buf pointer to a memory buffer + /// \param size length of the memory buffer ArrayXorSink(byte *buf, size_t size) : ArraySink(buf, size) {} @@ -1212,26 +1212,26 @@ public: byte * CreatePutSpace(size_t &size) {return BufferedTransformation::CreatePutSpace(size);} }; -//! \class StringStore -//! \brief String-based implementation of Store interface -//! \since Crypto++ 4.0 +/// \class StringStore +/// \brief String-based implementation of Store interface +/// \since Crypto++ 4.0 class StringStore : public Store { public: - //! \brief Construct a StringStore - //! \param string pointer to a C-String + /// \brief Construct a StringStore + /// \param string pointer to a C-String StringStore(const char *string = NULLPTR) {StoreInitialize(MakeParameters("InputBuffer", ConstByteArrayParameter(string)));} - //! \brief Construct a StringStore - //! \param string pointer to a memory buffer - //! \param length size of the memory buffer + /// \brief Construct a StringStore + /// \param string pointer to a memory buffer + /// \param length size of the memory buffer StringStore(const byte *string, size_t length) {StoreInitialize(MakeParameters("InputBuffer", ConstByteArrayParameter(string, length)));} - //! \brief Construct a StringStore - //! \tparam T std::basic_string type - //! \param string reference to a std::basic_string type + /// \brief Construct a StringStore + /// \tparam T std::basic_string type + /// \param string reference to a std::basic_string type template StringStore(const T &string) {StoreInitialize(MakeParameters("InputBuffer", ConstByteArrayParameter(string)));} @@ -1245,9 +1245,9 @@ private: size_t m_length, m_count; }; -//! \class RandomNumberStore -//! \brief RNG-based implementation of Source interface -//! \since Crypto++ 4.0 +/// \class RandomNumberStore +/// \brief RNG-based implementation of Source interface +/// \since Crypto++ 4.0 class CRYPTOPP_DLL RandomNumberStore : public Store { public: @@ -1276,8 +1276,8 @@ private: lword m_length, m_count; }; -//! \brief Empty store -//! \since Crypto++ 5.0 +/// \brief Empty store +/// \since Crypto++ 5.0 class CRYPTOPP_DLL NullStore : public Store { public: @@ -1292,73 +1292,73 @@ private: lword m_size; }; -//! \class Source -//! \brief Implementation of BufferedTransformation's attachment interface -//! \details Source is a cornerstone of the Pipeline trinitiy. Data flows from -//! Sources, through Filters, and then terminates in Sinks. The difference -//! between a Source and Filter is a Source \a pumps data, while a Filter does -//! not. The difference between a Filter and a Sink is a Filter allows an -//! attached transformation, while a Sink does not. -//! \details See the discussion of BufferedTransformation in cryptlib.h for -//! more details. -//! \sa Store and SourceTemplate -//! \since Crypto++ 1.0 +/// \class Source +/// \brief Implementation of BufferedTransformation's attachment interface +/// \details Source is a cornerstone of the Pipeline trinitiy. Data flows from +/// Sources, through Filters, and then terminates in Sinks. The difference +/// between a Source and Filter is a Source \a pumps data, while a Filter does +/// not. The difference between a Filter and a Sink is a Filter allows an +/// attached transformation, while a Sink does not. +/// \details See the discussion of BufferedTransformation in cryptlib.h for +/// more details. +/// \sa Store and SourceTemplate +/// \since Crypto++ 1.0 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Source : public InputRejecting { public: virtual ~Source() {} - //! \brief Construct a Source - //! \param attachment an optional attached transformation + /// \brief Construct a Source + /// \param attachment an optional attached transformation Source(BufferedTransformation *attachment = NULLPTR) {Source::Detach(attachment);} - //! \name PIPELINE + /// \name PIPELINE //@{ - //! \brief Pump data to attached transformation - //! \param pumpMax the maximpum number of bytes to pump - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) - //! \details Internally, Pump() calls Pump2(). - //! \note pumpMax is a \p lword, which is a 64-bit value that typically uses \p LWORD_MAX. The default - //! argument is a \p size_t that uses \p SIZE_MAX, and it can be 32-bits or 64-bits. + /// \brief Pump data to attached transformation + /// \param pumpMax the maximpum number of bytes to pump + /// \returns the number of bytes that remain in the block (i.e., bytes not processed) + /// \details Internally, Pump() calls Pump2(). + /// \note pumpMax is a \p lword, which is a 64-bit value that typically uses \p LWORD_MAX. The default + /// argument is a \p size_t that uses \p SIZE_MAX, and it can be 32-bits or 64-bits. lword Pump(lword pumpMax=(size_t)SIZE_MAX) {Pump2(pumpMax); return pumpMax;} - //! \brief Pump messages to attached transformation - //! \param count the maximpum number of messages to pump - //! \returns TODO - //! \details Internally, PumpMessages() calls PumpMessages2(). + /// \brief Pump messages to attached transformation + /// \param count the maximpum number of messages to pump + /// \returns TODO + /// \details Internally, PumpMessages() calls PumpMessages2(). unsigned int PumpMessages(unsigned int count=UINT_MAX) {PumpMessages2(count); return count;} - //! \brief Pump all data to attached transformation - //! \details Internally, PumpAll() calls PumpAll2(). + /// \brief Pump all data to attached transformation + /// \details Internally, PumpAll() calls PumpAll2(). void PumpAll() {PumpAll2();} - //! \brief Pump data to attached transformation - //! \param byteCount the maximpum number of bytes to pump - //! \param blocking specifies whether the object should block when processing input - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) - //! \details byteCount is an \a IN and \a OUT parameter. When the call is made, byteCount is the - //! requested size of the pump. When the call returns, byteCount is the number of bytes that - //! were pumped. + /// \brief Pump data to attached transformation + /// \param byteCount the maximpum number of bytes to pump + /// \param blocking specifies whether the object should block when processing input + /// \returns the number of bytes that remain in the block (i.e., bytes not processed) + /// \details byteCount is an \a IN and \a OUT parameter. When the call is made, byteCount is the + /// requested size of the pump. When the call returns, byteCount is the number of bytes that + /// were pumped. virtual size_t Pump2(lword &byteCount, bool blocking=true) =0; - //! \brief Pump messages to attached transformation - //! \param messageCount the maximpum number of messages to pump - //! \param blocking specifies whether the object should block when processing input - //! \details messageCount is an IN and OUT parameter. + /// \brief Pump messages to attached transformation + /// \param messageCount the maximpum number of messages to pump + /// \param blocking specifies whether the object should block when processing input + /// \details messageCount is an IN and OUT parameter. virtual size_t PumpMessages2(unsigned int &messageCount, bool blocking=true) =0; - //! \brief Pump all data to attached transformation - //! \param blocking specifies whether the object should block when processing input - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + /// \brief Pump all data to attached transformation + /// \param blocking specifies whether the object should block when processing input + /// \returns the number of bytes that remain in the block (i.e., bytes not processed) virtual size_t PumpAll2(bool blocking=true); - //! \brief Determines if the Source is exhausted - //! \returns true if the source has been exhausted + /// \brief Determines if the Source is exhausted + /// \returns true if the source has been exhausted virtual bool SourceExhausted() const =0; //@} @@ -1372,18 +1372,18 @@ protected: } }; -//! \class SourceTemplate -//! \brief Transform a Store into a Source -//! \tparam T the class or type -//! \since Crypto++ 5.0 +/// \class SourceTemplate +/// \brief Transform a Store into a Source +/// \tparam T the class or type +/// \since Crypto++ 5.0 template class SourceTemplate : public Source { public: virtual ~SourceTemplate() {} - //! \brief Construct a SourceTemplate - //! \param attachment an attached transformation + /// \brief Construct a SourceTemplate + /// \param attachment an attached transformation SourceTemplate(BufferedTransformation *attachment) : Source(attachment) {} void IsolatedInitialize(const NameValuePairs ¶meters) @@ -1405,49 +1405,49 @@ protected: T m_store; }; -//! \class SourceTemplate -//! \brief String-based implementation of the Source interface -//! \since Crypto++ 4.0 +/// \class SourceTemplate +/// \brief String-based implementation of the Source interface +/// \since Crypto++ 4.0 class CRYPTOPP_DLL StringSource : public SourceTemplate { public: - //! \brief Construct a StringSource - //! \param attachment an optional attached transformation + /// \brief Construct a StringSource + /// \param attachment an optional attached transformation StringSource(BufferedTransformation *attachment = NULLPTR) : SourceTemplate(attachment) {} - //! \brief Construct a StringSource - //! \param string C-String - //! \param pumpAll flag indicating if source data should be pumped to its attached transformation - //! \param attachment an optional attached transformation + /// \brief Construct a StringSource + /// \param string C-String + /// \param pumpAll flag indicating if source data should be pumped to its attached transformation + /// \param attachment an optional attached transformation StringSource(const char *string, bool pumpAll, BufferedTransformation *attachment = NULLPTR) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters("InputBuffer", ConstByteArrayParameter(string)));} - //! \brief Construct a StringSource - //! \param string binary byte array - //! \param length size of the byte array - //! \param pumpAll flag indicating if source data should be pumped to its attached transformation - //! \param attachment an optional attached transformation + /// \brief Construct a StringSource + /// \param string binary byte array + /// \param length size of the byte array + /// \param pumpAll flag indicating if source data should be pumped to its attached transformation + /// \param attachment an optional attached transformation StringSource(const byte *string, size_t length, bool pumpAll, BufferedTransformation *attachment = NULLPTR) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters("InputBuffer", ConstByteArrayParameter(string, length)));} - //! \brief Construct a StringSource - //! \param string std::string - //! \param pumpAll flag indicating if source data should be pumped to its attached transformation - //! \param attachment an optional attached transformation + /// \brief Construct a StringSource + /// \param string std::string + /// \param pumpAll flag indicating if source data should be pumped to its attached transformation + /// \param attachment an optional attached transformation StringSource(const std::string &string, bool pumpAll, BufferedTransformation *attachment = NULLPTR) : SourceTemplate(attachment) {SourceInitialize(pumpAll, MakeParameters("InputBuffer", ConstByteArrayParameter(string)));} }; -//! \class ArraySource -//! \brief Pointer-based implementation of the Source interface -//! \details ArraySource is a typedef for StringSource. Use the third constructor for an array source. -//! The third constructor takes a pointer and length. -//! \since Crypto++ 5.6.0 +/// \class ArraySource +/// \brief Pointer-based implementation of the Source interface +/// \details ArraySource is a typedef for StringSource. Use the third constructor for an array source. +/// The third constructor takes a pointer and length. +/// \since Crypto++ 5.6.0 DOCUMENTED_TYPEDEF(StringSource, ArraySource) -//! \brief RNG-based implementation of Source interface -//! \since Crypto++ 4.0 +/// \brief RNG-based implementation of Source interface +/// \since Crypto++ 4.0 class CRYPTOPP_DLL RandomNumberSource : public SourceTemplate { public: diff --git a/fips140.h b/fips140.h index eb276125..c8f4b1cd 100644 --- a/fips140.h +++ b/fips140.h @@ -1,12 +1,12 @@ // fips140.h - originally written and placed in the public domain by Wei Dai -//! \file fips140.h -//! \brief Classes and functions for the FIPS 140-2 validated library -//! \details The FIPS validated library is only available on Windows as a DLL. Once compiled, -//! the library is always in FIPS mode contingent upon successful execution of -//! DoPowerUpSelfTest() or DoDllPowerUpSelfTest(). -//! \sa Visual Studio and -//! config.h on the Crypto++ wiki. +/// \file fips140.h +/// \brief Classes and functions for the FIPS 140-2 validated library +/// \details The FIPS validated library is only available on Windows as a DLL. Once compiled, +/// the library is always in FIPS mode contingent upon successful execution of +/// DoPowerUpSelfTest() or DoDllPowerUpSelfTest(). +/// \sa Visual Studio and +/// config.h on the Crypto++ wiki. #ifndef CRYPTOPP_FIPS140_H #define CRYPTOPP_FIPS140_H @@ -16,76 +16,76 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SelfTestFailure -//! Exception thrown when a crypto algorithm is used after a self test fails -//! \details The self tests for an algorithm are performed by Algortihm class -//! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. +/// \class SelfTestFailure +/// Exception thrown when a crypto algorithm is used after a self test fails +/// \details The self tests for an algorithm are performed by Algortihm class +/// when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. class CRYPTOPP_DLL SelfTestFailure : public Exception { public: explicit SelfTestFailure(const std::string &s) : Exception(OTHER_ERROR, s) {} }; -//! \brief Determines whether the library provides FIPS validated cryptography -//! \returns true if FIPS 140-2 validated features were enabled at compile time. -//! \details true if FIPS 140-2 validated features were enabled at compile time, -//! false otherwise. -//! \note FIPS mode is enabled at compile time. A program or other module cannot -//! arbitrarily enter or exit the mode. +/// \brief Determines whether the library provides FIPS validated cryptography +/// \returns true if FIPS 140-2 validated features were enabled at compile time. +/// \details true if FIPS 140-2 validated features were enabled at compile time, +/// false otherwise. +/// \note FIPS mode is enabled at compile time. A program or other module cannot +/// arbitrarily enter or exit the mode. CRYPTOPP_DLL bool CRYPTOPP_API FIPS_140_2_ComplianceEnabled(); -//! \brief Status of the power-up self test +/// \brief Status of the power-up self test enum PowerUpSelfTestStatus { - //! \brief The self tests have not been performed. + /// \brief The self tests have not been performed. POWER_UP_SELF_TEST_NOT_DONE, - //! \brief The self tests were executed via DoPowerUpSelfTest() or - //! DoDllPowerUpSelfTest(), but the result was failure. + /// \brief The self tests were executed via DoPowerUpSelfTest() or + /// DoDllPowerUpSelfTest(), but the result was failure. POWER_UP_SELF_TEST_FAILED, - //! \brief The self tests were executed via DoPowerUpSelfTest() or - //! DoDllPowerUpSelfTest(), and the result was success. + /// \brief The self tests were executed via DoPowerUpSelfTest() or + /// DoDllPowerUpSelfTest(), and the result was success. POWER_UP_SELF_TEST_PASSED }; -//! \brief Performs the power-up self test -//! \param moduleFilename the fully qualified name of the module -//! \param expectedModuleMac the expected MAC of the components protected by the integrity check -//! \details Performs the power-up self test, and sets the self test status to -//! POWER_UP_SELF_TEST_PASSED or POWER_UP_SELF_TEST_FAILED. -//! \details The self tests for an algorithm are performed by the Algortihm class -//! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. +/// \brief Performs the power-up self test +/// \param moduleFilename the fully qualified name of the module +/// \param expectedModuleMac the expected MAC of the components protected by the integrity check +/// \details Performs the power-up self test, and sets the self test status to +/// POWER_UP_SELF_TEST_PASSED or POWER_UP_SELF_TEST_FAILED. +/// \details The self tests for an algorithm are performed by the Algortihm class +/// when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. CRYPTOPP_DLL void CRYPTOPP_API DoPowerUpSelfTest(const char *moduleFilename, const byte *expectedModuleMac); -//! \brief Performs the power-up self test on the DLL -//! \details Performs the power-up self test using the filename of this DLL and the -//! embedded module MAC, and sets the self test status to POWER_UP_SELF_TEST_PASSED or -//! POWER_UP_SELF_TEST_FAILED. -//! \details The self tests for an algorithm are performed by the Algortihm class -//! when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. +/// \brief Performs the power-up self test on the DLL +/// \details Performs the power-up self test using the filename of this DLL and the +/// embedded module MAC, and sets the self test status to POWER_UP_SELF_TEST_PASSED or +/// POWER_UP_SELF_TEST_FAILED. +/// \details The self tests for an algorithm are performed by the Algortihm class +/// when CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined. CRYPTOPP_DLL void CRYPTOPP_API DoDllPowerUpSelfTest(); -//! \brief Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED -//! \details Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED to simulate failure. +/// \brief Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED +/// \details Sets the power-up self test status to POWER_UP_SELF_TEST_FAILED to simulate failure. CRYPTOPP_DLL void CRYPTOPP_API SimulatePowerUpSelfTestFailure(); -//! \brief Provides the current power-up self test status -//! \returns the current power-up self test status +/// \brief Provides the current power-up self test status +/// \returns the current power-up self test status CRYPTOPP_DLL PowerUpSelfTestStatus CRYPTOPP_API GetPowerUpSelfTestStatus(); #ifndef CRYPTOPP_DOXYGEN_PROCESSING typedef PowerUpSelfTestStatus (CRYPTOPP_API * PGetPowerUpSelfTestStatus)(); #endif -//! \brief Class object that calculates the MAC on the module -//! \returns the MAC for the module +/// \brief Class object that calculates the MAC on the module +/// \returns the MAC for the module CRYPTOPP_DLL MessageAuthenticationCode * CRYPTOPP_API NewIntegrityCheckingMAC(); -//! \brief Verifies the MAC on the module -//! \param moduleFilename the fully qualified name of the module -//! \param expectedModuleMac the expected MAC of the components protected by the integrity check -//! \param pActualMac the actual MAC of the components calculated by the integrity check -//! \param pMacFileLocation the offest of the MAC in the PE/PE+ module -//! \returns true if the MAC is valid, false otherwise +/// \brief Verifies the MAC on the module +/// \param moduleFilename the fully qualified name of the module +/// \param expectedModuleMac the expected MAC of the components protected by the integrity check +/// \param pActualMac the actual MAC of the components calculated by the integrity check +/// \param pMacFileLocation the offest of the MAC in the PE/PE+ module +/// \returns true if the MAC is valid, false otherwise CRYPTOPP_DLL bool CRYPTOPP_API IntegrityCheckModule(const char *moduleFilename, const byte *expectedModuleMac, SecByteBlock *pActualMac = NULLPTR, unsigned long *pMacFileLocation = NULLPTR); #ifndef CRYPTOPP_DOXYGEN_PROCESSING @@ -101,11 +101,11 @@ void SignaturePairwiseConsistencyTest_FIPS_140_Only(const PK_Signer &signer, con void EncryptionPairwiseConsistencyTest_FIPS_140_Only(const PK_Encryptor &encryptor, const PK_Decryptor &decryptor); #endif -//! \brief The placeholder used prior to embedding the actual MAC in the module. -//! \details After the DLL is built but before it is MAC'd, the string CRYPTOPP_DUMMY_DLL_MAC -//! is used as a placeholder for the actual MAC. A post-build step is performed which calculates -//! the MAC of the DLL and embeds it in the module. The actual MAC is written by the -//! cryptest.exe program using the mac_dll subcommand. +/// \brief The placeholder used prior to embedding the actual MAC in the module. +/// \details After the DLL is built but before it is MAC'd, the string CRYPTOPP_DUMMY_DLL_MAC +/// is used as a placeholder for the actual MAC. A post-build step is performed which calculates +/// the MAC of the DLL and embeds it in the module. The actual MAC is written by the +/// cryptest.exe program using the mac_dll subcommand. #define CRYPTOPP_DUMMY_DLL_MAC "MAC_51f34b8db820ae8" NAMESPACE_END diff --git a/gcm.h b/gcm.h index 0f523802..ba4d2b44 100644 --- a/gcm.h +++ b/gcm.h @@ -1,8 +1,8 @@ // gcm.h - originally written and placed in the public domain by Wei Dai -//! \file gcm.h -//! \brief GCM block cipher mode of operation -//! \since Crypto++ 5.6.0 +/// \file gcm.h +/// \brief GCM block cipher mode of operation +/// \since Crypto++ 5.6.0 #ifndef CRYPTOPP_GCM_H #define CRYPTOPP_GCM_H @@ -12,18 +12,18 @@ NAMESPACE_BEGIN(CryptoPP) -//! \enum GCM_TablesOption -//! \brief GCM table size options +/// \enum GCM_TablesOption +/// \brief GCM table size options enum GCM_TablesOption { - //! \brief Use a table with 2K entries + /// \brief Use a table with 2K entries GCM_2K_Tables, - //! \brief Use a table with 64K entries + /// \brief Use a table with 64K entries GCM_64K_Tables}; -//! \class GCM_Base -//! \brief GCM block cipher base implementation -//! \details Base implementation of the AuthenticatedSymmetricCipher interface -//! \since Crypto++ 5.6.0 +/// \class GCM_Base +/// \brief GCM block cipher base implementation +/// \details Base implementation of the AuthenticatedSymmetricCipher interface +/// \since Crypto++ 5.6.0 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE GCM_Base : public AuthenticatedSymmetricCipherBase { public: @@ -91,12 +91,12 @@ protected: enum {REQUIRED_BLOCKSIZE = 16, HASH_BLOCKSIZE = 16}; }; -//! \class GCM_Final -//! \brief GCM block cipher final implementation -//! \tparam T_BlockCipher block cipher -//! \tparam T_TablesOption table size, either \p GCM_2K_Tables or \p GCM_64K_Tables -//! \tparam T_IsEncryption direction in which to operate the cipher -//! \since Crypto++ 5.6.0 +/// \class GCM_Final +/// \brief GCM block cipher final implementation +/// \tparam T_BlockCipher block cipher +/// \tparam T_TablesOption table size, either \p GCM_2K_Tables or \p GCM_64K_Tables +/// \tparam T_IsEncryption direction in which to operate the cipher +/// \since Crypto++ 5.6.0 template class GCM_Final : public GCM_Base { @@ -112,16 +112,16 @@ private: typename T_BlockCipher::Encryption m_cipher; }; -//! \class GCM -//! \brief GCM block cipher mode of operation -//! \tparam T_BlockCipher block cipher -//! \tparam T_TablesOption table size, either \p GCM_2K_Tables or \p GCM_64K_Tables -//! \details \p GCM provides the \p Encryption and \p Decryption typedef. See GCM_Base -//! and GCM_Final for the AuthenticatedSymmetricCipher implementation. -//! \sa GCM Mode and -//! Modes of Operation -//! on the Crypto++ wiki. -//! \since Crypto++ 5.6.0 +/// \class GCM +/// \brief GCM block cipher mode of operation +/// \tparam T_BlockCipher block cipher +/// \tparam T_TablesOption table size, either \p GCM_2K_Tables or \p GCM_64K_Tables +/// \details \p GCM provides the \p Encryption and \p Decryption typedef. See GCM_Base +/// and GCM_Final for the AuthenticatedSymmetricCipher implementation. +/// \sa GCM Mode and +/// Modes of Operation +/// on the Crypto++ wiki. +/// \since Crypto++ 5.6.0 template struct GCM : public AuthenticatedSymmetricCipherDocumentation { diff --git a/gf256.h b/gf256.h index 4a3cd83d..9cef8309 100644 --- a/gf256.h +++ b/gf256.h @@ -1,7 +1,7 @@ // gf256.h - originally written and placed in the public domain by Wei Dai -//! \file gf256.h -//! \brief Classes and functions for schemes over GF(256) +/// \file gf256.h +/// \brief Classes and functions for schemes over GF(256) #ifndef CRYPTOPP_GF256_H #define CRYPTOPP_GF256_H @@ -11,7 +11,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief GF(256) with polynomial basis +/// \brief GF(256) with polynomial basis class GF256 { public: diff --git a/gf2_32.h b/gf2_32.h index 845c7c02..f0d229df 100644 --- a/gf2_32.h +++ b/gf2_32.h @@ -1,7 +1,7 @@ // gf2_32.h - originally written and placed in the public domain by Wei Dai -//! \file gf2_32.h -//! \brief Classes and functions for schemes over GF(2^32) +/// \file gf2_32.h +/// \brief Classes and functions for schemes over GF(2^32) #ifndef CRYPTOPP_GF2_32_H #define CRYPTOPP_GF2_32_H @@ -12,7 +12,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief GF(2^32) with polynomial basis +/// \brief GF(2^32) with polynomial basis class GF2_32 { public: diff --git a/gf2n.h b/gf2n.h index 381a9ba8..40cf3934 100644 --- a/gf2n.h +++ b/gf2n.h @@ -1,7 +1,7 @@ // gf2n.h - originally written and placed in the public domain by Wei Dai -//! \file gf2n.h -//! \brief Classes and functions for schemes over GF(2^n) +/// \file gf2n.h +/// \brief Classes and functions for schemes over GF(2^n) #ifndef CRYPTOPP_GF2N_H #define CRYPTOPP_GF2N_H @@ -21,14 +21,14 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Polynomial with Coefficients in GF(2) +/// \brief Polynomial with Coefficients in GF(2) /*! \nosubgrouping */ class CRYPTOPP_DLL PolynomialMod2 { public: - //! \name ENUMS, EXCEPTIONS, and TYPEDEFS + /// \name ENUMS, EXCEPTIONS, and TYPEDEFS //@{ - //! \brief Excpetion thrown when divide by zero is encountered + /// \brief Excpetion thrown when divide by zero is encountered class DivideByZero : public Exception { public: @@ -38,209 +38,209 @@ public: typedef unsigned int RandomizationParameter; //@} - //! \name CREATORS + /// \name CREATORS //@{ - //! \brief Construct the zero polynomial + /// \brief Construct the zero polynomial PolynomialMod2(); - //! Copy construct a PolynomialMod2 + /// Copy construct a PolynomialMod2 PolynomialMod2(const PolynomialMod2& t); - //! \brief Construct a PolynomialMod2 from a word - //! \details value should be encoded with the least significant bit as coefficient to x^0 - //! and most significant bit as coefficient to x^(WORD_BITS-1) - //! bitLength denotes how much memory to allocate initially + /// \brief Construct a PolynomialMod2 from a word + /// \details value should be encoded with the least significant bit as coefficient to x^0 + /// and most significant bit as coefficient to x^(WORD_BITS-1) + /// bitLength denotes how much memory to allocate initially PolynomialMod2(word value, size_t bitLength=WORD_BITS); - //! \brief Construct a PolynomialMod2 from big-endian byte array + /// \brief Construct a PolynomialMod2 from big-endian byte array PolynomialMod2(const byte *encodedPoly, size_t byteCount) {Decode(encodedPoly, byteCount);} - //! \brief Construct a PolynomialMod2 from big-endian form stored in a BufferedTransformation + /// \brief Construct a PolynomialMod2 from big-endian form stored in a BufferedTransformation PolynomialMod2(BufferedTransformation &encodedPoly, size_t byteCount) {Decode(encodedPoly, byteCount);} - //! \brief Create a uniformly distributed random polynomial - //! \details Create a random polynomial uniformly distributed over all polynomials with degree less than bitcount + /// \brief Create a uniformly distributed random polynomial + /// \details Create a random polynomial uniformly distributed over all polynomials with degree less than bitcount PolynomialMod2(RandomNumberGenerator &rng, size_t bitcount) {Randomize(rng, bitcount);} - //! \brief Provides x^i - //! \returns x^i + /// \brief Provides x^i + /// \returns x^i static PolynomialMod2 CRYPTOPP_API Monomial(size_t i); - //! \brief Provides x^t0 + x^t1 + x^t2 - //! \returns x^t0 + x^t1 + x^t2 + /// \brief Provides x^t0 + x^t1 + x^t2 + /// \returns x^t0 + x^t1 + x^t2 static PolynomialMod2 CRYPTOPP_API Trinomial(size_t t0, size_t t1, size_t t2); - //! \brief Provides x^t0 + x^t1 + x^t2 + x^t3 + x^t4 - //! \returns x^t0 + x^t1 + x^t2 + x^t3 + x^t4 + /// \brief Provides x^t0 + x^t1 + x^t2 + x^t3 + x^t4 + /// \returns x^t0 + x^t1 + x^t2 + x^t3 + x^t4 static PolynomialMod2 CRYPTOPP_API Pentanomial(size_t t0, size_t t1, size_t t2, size_t t3, size_t t4); - //! \brief Provides x^(n-1) + ... + x + 1 - //! \returns x^(n-1) + ... + x + 1 + /// \brief Provides x^(n-1) + ... + x + 1 + /// \returns x^(n-1) + ... + x + 1 static PolynomialMod2 CRYPTOPP_API AllOnes(size_t n); - //! \brief The Zero polinomial - //! \returns the zero polynomial + /// \brief The Zero polinomial + /// \returns the zero polynomial static const PolynomialMod2 & CRYPTOPP_API Zero(); - //! \brief The One polinomial - //! \returns the one polynomial + /// \brief The One polinomial + /// \returns the one polynomial static const PolynomialMod2 & CRYPTOPP_API One(); //@} - //! \name ENCODE/DECODE + /// \name ENCODE/DECODE //@{ - //! minimum number of bytes to encode this polynomial + /// minimum number of bytes to encode this polynomial /*! MinEncodedSize of 0 is 1 */ unsigned int MinEncodedSize() const {return STDMAX(1U, ByteCount());} - //! encode in big-endian format - //! \details if outputLen < MinEncodedSize, the most significant bytes will be dropped - //! if outputLen > MinEncodedSize, the most significant bytes will be padded + /// encode in big-endian format + /// \details if outputLen < MinEncodedSize, the most significant bytes will be dropped + /// if outputLen > MinEncodedSize, the most significant bytes will be padded void Encode(byte *output, size_t outputLen) const; - //! + /// void Encode(BufferedTransformation &bt, size_t outputLen) const; - //! + /// void Decode(const byte *input, size_t inputLen); - //! + /// //* Precondition: bt.MaxRetrievable() >= inputLen void Decode(BufferedTransformation &bt, size_t inputLen); - //! encode value as big-endian octet string + /// encode value as big-endian octet string void DEREncodeAsOctetString(BufferedTransformation &bt, size_t length) const; - //! decode value as big-endian octet string + /// decode value as big-endian octet string void BERDecodeAsOctetString(BufferedTransformation &bt, size_t length); //@} - //! \name ACCESSORS + /// \name ACCESSORS //@{ - //! number of significant bits = Degree() + 1 + /// number of significant bits = Degree() + 1 unsigned int BitCount() const; - //! number of significant bytes = ceiling(BitCount()/8) + /// number of significant bytes = ceiling(BitCount()/8) unsigned int ByteCount() const; - //! number of significant words = ceiling(ByteCount()/sizeof(word)) + /// number of significant words = ceiling(ByteCount()/sizeof(word)) unsigned int WordCount() const; - //! return the n-th bit, n=0 being the least significant bit + /// return the n-th bit, n=0 being the least significant bit bool GetBit(size_t n) const {return GetCoefficient(n)!=0;} - //! return the n-th byte + /// return the n-th byte byte GetByte(size_t n) const; - //! the zero polynomial will return a degree of -1 + /// the zero polynomial will return a degree of -1 signed int Degree() const {return (signed int)(BitCount()-1U);} - //! degree + 1 + /// degree + 1 unsigned int CoefficientCount() const {return BitCount();} - //! return coefficient for x^i + /// return coefficient for x^i int GetCoefficient(size_t i) const {return (i/WORD_BITS < reg.size()) ? int(reg[i/WORD_BITS] >> (i % WORD_BITS)) & 1 : 0;} - //! return coefficient for x^i + /// return coefficient for x^i int operator[](unsigned int i) const {return GetCoefficient(i);} - //! + /// bool IsZero() const {return !*this;} - //! + /// bool Equals(const PolynomialMod2 &rhs) const; //@} - //! \name MANIPULATORS + /// \name MANIPULATORS //@{ - //! + /// PolynomialMod2& operator=(const PolynomialMod2& t); - //! + /// PolynomialMod2& operator&=(const PolynomialMod2& t); - //! + /// PolynomialMod2& operator^=(const PolynomialMod2& t); - //! + /// PolynomialMod2& operator+=(const PolynomialMod2& t) {return *this ^= t;} - //! + /// PolynomialMod2& operator-=(const PolynomialMod2& t) {return *this ^= t;} - //! + /// PolynomialMod2& operator*=(const PolynomialMod2& t); - //! + /// PolynomialMod2& operator/=(const PolynomialMod2& t); - //! + /// PolynomialMod2& operator%=(const PolynomialMod2& t); - //! + /// PolynomialMod2& operator<<=(unsigned int); - //! + /// PolynomialMod2& operator>>=(unsigned int); - //! + /// void Randomize(RandomNumberGenerator &rng, size_t bitcount); - //! + /// void SetBit(size_t i, int value = 1); - //! set the n-th byte to value + /// set the n-th byte to value void SetByte(size_t n, byte value); - //! + /// void SetCoefficient(size_t i, int value) {SetBit(i, value);} - //! + /// void swap(PolynomialMod2 &a) {reg.swap(a.reg);} //@} - //! \name UNARY OPERATORS + /// \name UNARY OPERATORS //@{ - //! + /// bool operator!() const; - //! + /// PolynomialMod2 operator+() const {return *this;} - //! + /// PolynomialMod2 operator-() const {return *this;} //@} - //! \name BINARY OPERATORS + /// \name BINARY OPERATORS //@{ - //! + /// PolynomialMod2 And(const PolynomialMod2 &b) const; - //! + /// PolynomialMod2 Xor(const PolynomialMod2 &b) const; - //! + /// PolynomialMod2 Plus(const PolynomialMod2 &b) const {return Xor(b);} - //! + /// PolynomialMod2 Minus(const PolynomialMod2 &b) const {return Xor(b);} - //! + /// PolynomialMod2 Times(const PolynomialMod2 &b) const; - //! + /// PolynomialMod2 DividedBy(const PolynomialMod2 &b) const; - //! + /// PolynomialMod2 Modulo(const PolynomialMod2 &b) const; - //! + /// PolynomialMod2 operator>>(unsigned int n) const; - //! + /// PolynomialMod2 operator<<(unsigned int n) const; //@} - //! \name OTHER ARITHMETIC FUNCTIONS + /// \name OTHER ARITHMETIC FUNCTIONS //@{ - //! sum modulo 2 of all coefficients + /// sum modulo 2 of all coefficients unsigned int Parity() const; - //! check for irreducibility + /// check for irreducibility bool IsIrreducible() const; - //! is always zero since we're working modulo 2 + /// is always zero since we're working modulo 2 PolynomialMod2 Doubled() const {return Zero();} - //! + /// PolynomialMod2 Squared() const; - //! only 1 is a unit + /// only 1 is a unit bool IsUnit() const {return Equals(One());} - //! return inverse if *this is a unit, otherwise return 0 + /// return inverse if *this is a unit, otherwise return 0 PolynomialMod2 MultiplicativeInverse() const {return IsUnit() ? One() : Zero();} - //! greatest common divisor + /// greatest common divisor static PolynomialMod2 CRYPTOPP_API Gcd(const PolynomialMod2 &a, const PolynomialMod2 &n); - //! calculate multiplicative inverse of *this mod n + /// calculate multiplicative inverse of *this mod n PolynomialMod2 InverseMod(const PolynomialMod2 &) const; - //! calculate r and q such that (a == d*q + r) && (deg(r) < deg(d)) + /// calculate r and q such that (a == d*q + r) && (deg(r) < deg(d)) static void CRYPTOPP_API Divide(PolynomialMod2 &r, PolynomialMod2 &q, const PolynomialMod2 &a, const PolynomialMod2 &d); //@} - //! \name INPUT/OUTPUT + /// \name INPUT/OUTPUT //@{ - //! + /// friend std::ostream& operator<<(std::ostream& out, const PolynomialMod2 &a); //@} @@ -250,37 +250,37 @@ private: SecWordBlock reg; }; -//! +/// inline bool operator==(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Equals(b);} -//! +/// inline bool operator!=(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return !(a==b);} -//! compares degree +/// compares degree inline bool operator> (const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Degree() > b.Degree();} -//! compares degree +/// compares degree inline bool operator>=(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Degree() >= b.Degree();} -//! compares degree +/// compares degree inline bool operator< (const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Degree() < b.Degree();} -//! compares degree +/// compares degree inline bool operator<=(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Degree() <= b.Degree();} -//! +/// inline CryptoPP::PolynomialMod2 operator&(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.And(b);} -//! +/// inline CryptoPP::PolynomialMod2 operator^(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Xor(b);} -//! +/// inline CryptoPP::PolynomialMod2 operator+(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Plus(b);} -//! +/// inline CryptoPP::PolynomialMod2 operator-(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Minus(b);} -//! +/// inline CryptoPP::PolynomialMod2 operator*(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Times(b);} -//! +/// inline CryptoPP::PolynomialMod2 operator/(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.DividedBy(b);} -//! +/// inline CryptoPP::PolynomialMod2 operator%(const CryptoPP::PolynomialMod2 &a, const CryptoPP::PolynomialMod2 &b) {return a.Modulo(b);} // CodeWarrior 8 workaround: put these template instantiations after overloaded operator declarations, @@ -291,7 +291,7 @@ CRYPTOPP_DLL_TEMPLATE_CLASS AbstractEuclideanDomain; CRYPTOPP_DLL_TEMPLATE_CLASS EuclideanDomainOf; CRYPTOPP_DLL_TEMPLATE_CLASS QuotientRing >; -//! \brief GF(2^n) with Polynomial Basis +/// \brief GF(2^n) with Polynomial Basis class CRYPTOPP_DLL GF2NP : public QuotientRing > { public: @@ -327,7 +327,7 @@ protected: unsigned int m; }; -//! \brief GF(2^n) with Trinomial Basis +/// \brief GF(2^n) with Trinomial Basis class CRYPTOPP_DLL GF2NT : public GF2NP { public: @@ -351,7 +351,7 @@ private: mutable PolynomialMod2 result; }; -//! \brief GF(2^n) with Pentanomial Basis +/// \brief GF(2^n) with Pentanomial Basis class CRYPTOPP_DLL GF2NPP : public GF2NP { public: diff --git a/gfpcrypt.h b/gfpcrypt.h index f2baa2a4..81689f89 100644 --- a/gfpcrypt.h +++ b/gfpcrypt.h @@ -2,8 +2,8 @@ // RFC6979 deterministic signatures added by Douglas Roark // ECGDSA added by Jeffrey Walton -//! \file gfpcrypt.h -//! \brief Classes and functions for schemes based on Discrete Logs (DL) over GF(p) +/// \file gfpcrypt.h +/// \brief Classes and functions for schemes based on Discrete Logs (DL) over GF(p) #ifndef CRYPTOPP_GFPCRYPT_H #define CRYPTOPP_GFPCRYPT_H @@ -30,8 +30,8 @@ NAMESPACE_BEGIN(CryptoPP) CRYPTOPP_DLL_TEMPLATE_CLASS DL_GroupParameters; -//! \class DL_GroupParameters_IntegerBased -//! \brief Integer-based GroupParameters specialization +/// \class DL_GroupParameters_IntegerBased +/// \brief Integer-based GroupParameters specialization class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE DL_GroupParameters_IntegerBased : public ASN1CryptoMaterial > { typedef DL_GroupParameters_IntegerBased ThisClass; @@ -39,30 +39,30 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE DL_GroupParameters_IntegerBased : public A public: virtual ~DL_GroupParameters_IntegerBased() {} - //! \brief Initialize a group parameters over integers - //! \param params the group parameters + /// \brief Initialize a group parameters over integers + /// \param params the group parameters void Initialize(const DL_GroupParameters_IntegerBased ¶ms) {Initialize(params.GetModulus(), params.GetSubgroupOrder(), params.GetSubgroupGenerator());} - //! \brief Create a group parameters over integers - //! \param rng a RandomNumberGenerator derived class - //! \param pbits the size of p, in bits - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a group parameters over integers + /// \param rng a RandomNumberGenerator derived class + /// \param pbits the size of p, in bits + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int pbits) {GenerateRandom(rng, MakeParameters("ModulusSize", (int)pbits));} - //! \brief Initialize a group parameters over integers - //! \param p the modulus - //! \param g the generator + /// \brief Initialize a group parameters over integers + /// \param p the modulus + /// \param g the generator void Initialize(const Integer &p, const Integer &g) {SetModulusAndSubgroupGenerator(p, g); SetSubgroupOrder(ComputeGroupOrder(p)/2);} - //! \brief Initialize a group parameters over integers - //! \param p the modulus - //! \param q the subgroup order - //! \param g the generator + /// \brief Initialize a group parameters over integers + /// \param p the modulus + /// \param q the subgroup order + /// \param g the generator void Initialize(const Integer &p, const Integer &q, const Integer &g) {SetModulusAndSubgroupGenerator(p, g); SetSubgroupOrder(q);} @@ -113,10 +113,10 @@ private: Integer m_q; }; -//! \class DL_GroupParameters_IntegerBasedImpl -//! \brief Integer-based GroupParameters default implementation -//! \tparam GROUP_PRECOMP group parameters precomputation specialization -//! \tparam BASE_PRECOMP base class precomputation specialization +/// \class DL_GroupParameters_IntegerBasedImpl +/// \brief Integer-based GroupParameters default implementation +/// \tparam GROUP_PRECOMP group parameters precomputation specialization +/// \tparam BASE_PRECOMP base class precomputation specialization template > class CRYPTOPP_NO_VTABLE DL_GroupParameters_IntegerBasedImpl : public DL_GroupParametersImpl { @@ -154,8 +154,8 @@ public: CRYPTOPP_DLL_TEMPLATE_CLASS DL_GroupParameters_IntegerBasedImpl; -//! \class DL_GroupParameters_GFP -//! \brief GF(p) group parameters +/// \class DL_GroupParameters_GFP +/// \brief GF(p) group parameters class CRYPTOPP_DLL DL_GroupParameters_GFP : public DL_GroupParameters_IntegerBasedImpl { public: @@ -179,8 +179,8 @@ protected: int GetFieldType() const {return 1;} }; -//! \class DL_GroupParameters_GFP -//! \brief GF(p) group parameters that default to safe primes +/// \class DL_GroupParameters_GFP +/// \brief GF(p) group parameters that default to safe primes class CRYPTOPP_DLL DL_GroupParameters_GFP_DefaultSafePrime : public DL_GroupParameters_GFP { public: @@ -192,9 +192,9 @@ protected: unsigned int GetDefaultSubgroupOrderSize(unsigned int modulusSize) const {return modulusSize-1;} }; -//! \class DL_Algorithm_GDSA -//! \brief GDSA algorithm -//! \tparam T FieldElement type or class +/// \class DL_Algorithm_GDSA +/// \brief GDSA algorithm +/// \tparam T FieldElement type or class template class DL_Algorithm_GDSA : public DL_ElgamalLikeSignatureAlgorithm { @@ -226,13 +226,13 @@ public: } }; -//! \class DL_Algorithm_DSA_RFC6979 -//! \brief DSA signature algorithm based on RFC 6979 -//! \tparam T FieldElement type or class -//! \tparam H HashTransformation derived class -//! \sa RFC 6979, Deterministic Usage of the -//! Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) -//! \since Crypto++ 6.0 +/// \class DL_Algorithm_DSA_RFC6979 +/// \brief DSA signature algorithm based on RFC 6979 +/// \tparam T FieldElement type or class +/// \tparam H HashTransformation derived class +/// \sa RFC 6979, Deterministic Usage of the +/// Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) +/// \since Crypto++ 6.0 template class DL_Algorithm_DSA_RFC6979 : public DL_Algorithm_GDSA, public DeterministicSignatureAlgorithm { @@ -394,14 +394,14 @@ private: mutable HMAC m_hmac; }; -//! \class DL_Algorithm_GDSA_ISO15946 -//! \brief German Digital Signature Algorithm -//! \tparam T FieldElement type or class -//! \details The Digital Signature Scheme ECGDSA does not define the algorithm over integers. Rather, the -//! signature algorithm is only defined over elliptic curves. However, The library design is such that the -//! generic algorithm reside in gfpcrypt.h. -//! \sa Erwin Hess, Marcus Schafheutle, and Pascale Serf -//! The Digital Signature Scheme ECGDSA (October 24, 2006) +/// \class DL_Algorithm_GDSA_ISO15946 +/// \brief German Digital Signature Algorithm +/// \tparam T FieldElement type or class +/// \details The Digital Signature Scheme ECGDSA does not define the algorithm over integers. Rather, the +/// signature algorithm is only defined over elliptic curves. However, The library design is such that the +/// generic algorithm reside in gfpcrypt.h. +/// \sa Erwin Hess, Marcus Schafheutle, and Pascale Serf +/// The Digital Signature Scheme ECGDSA (October 24, 2006) template class DL_Algorithm_GDSA_ISO15946 : public DL_ElgamalLikeSignatureAlgorithm { @@ -441,9 +441,9 @@ CRYPTOPP_DLL_TEMPLATE_CLASS DL_Algorithm_DSA_RFC6979; CRYPTOPP_DLL_TEMPLATE_CLASS DL_Algorithm_DSA_RFC6979; CRYPTOPP_DLL_TEMPLATE_CLASS DL_Algorithm_DSA_RFC6979; -//! \class DL_Algorithm_NR -//! \brief NR algorithm -//! \tparam T FieldElement type or class +/// \class DL_Algorithm_NR +/// \brief NR algorithm +/// \tparam T FieldElement type or class template class DL_Algorithm_NR : public DL_ElgamalLikeSignatureAlgorithm { @@ -471,34 +471,34 @@ public: } }; -//! \class DL_PublicKey_GFP -//! \brief Discrete Log (DL) public key in GF(p) groups -//! \tparam GP GroupParameters derived class -//! \details DSA public key format is defined in 7.3.3 of RFC 2459. The private key format is defined in 12.9 of PKCS #11 v2.10. +/// \class DL_PublicKey_GFP +/// \brief Discrete Log (DL) public key in GF(p) groups +/// \tparam GP GroupParameters derived class +/// \details DSA public key format is defined in 7.3.3 of RFC 2459. The private key format is defined in 12.9 of PKCS #11 v2.10. template class DL_PublicKey_GFP : public DL_PublicKeyImpl { public: virtual ~DL_PublicKey_GFP() {} - //! \brief Initialize a public key over GF(p) - //! \param params the group parameters - //! \param y the public element + /// \brief Initialize a public key over GF(p) + /// \param params the group parameters + /// \param y the public element void Initialize(const DL_GroupParameters_IntegerBased ¶ms, const Integer &y) {this->AccessGroupParameters().Initialize(params); this->SetPublicElement(y);} - //! \brief Initialize a public key over GF(p) - //! \param p the modulus - //! \param g the generator - //! \param y the public element + /// \brief Initialize a public key over GF(p) + /// \param p the modulus + /// \param g the generator + /// \param y the public element void Initialize(const Integer &p, const Integer &g, const Integer &y) {this->AccessGroupParameters().Initialize(p, g); this->SetPublicElement(y);} - //! \brief Initialize a public key over GF(p) - //! \param p the modulus - //! \param q the subgroup order - //! \param g the generator - //! \param y the public element + /// \brief Initialize a public key over GF(p) + /// \param p the modulus + /// \param q the subgroup order + /// \param g the generator + /// \param y the public element void Initialize(const Integer &p, const Integer &q, const Integer &g, const Integer &y) {this->AccessGroupParameters().Initialize(p, q, g); this->SetPublicElement(y);} @@ -509,63 +509,63 @@ public: {this->GetPublicElement().DEREncode(bt);} }; -//! \class DL_PrivateKey_GFP -//! \brief Discrete Log (DL) private key in GF(p) groups -//! \tparam GP GroupParameters derived class +/// \class DL_PrivateKey_GFP +/// \brief Discrete Log (DL) private key in GF(p) groups +/// \tparam GP GroupParameters derived class template class DL_PrivateKey_GFP : public DL_PrivateKeyImpl { public: virtual ~DL_PrivateKey_GFP(); - //! \brief Create a private key - //! \param rng a RandomNumberGenerator derived class - //! \param modulusBits the size of the modulus, in bits - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a private key + /// \param rng a RandomNumberGenerator derived class + /// \param modulusBits the size of the modulus, in bits + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits) {this->GenerateRandomWithKeySize(rng, modulusBits);} - //! \brief Create a private key - //! \param rng a RandomNumberGenerator derived class - //! \param p the modulus - //! \param g the generator - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a private key + /// \param rng a RandomNumberGenerator derived class + /// \param p the modulus + /// \param g the generator + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const Integer &p, const Integer &g) {this->GenerateRandom(rng, MakeParameters("Modulus", p)("SubgroupGenerator", g));} - //! \brief Create a private key - //! \param rng a RandomNumberGenerator derived class - //! \param p the modulus - //! \param q the subgroup order - //! \param g the generator - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a private key + /// \param rng a RandomNumberGenerator derived class + /// \param p the modulus + /// \param q the subgroup order + /// \param g the generator + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, const Integer &p, const Integer &q, const Integer &g) {this->GenerateRandom(rng, MakeParameters("Modulus", p)("SubgroupOrder", q)("SubgroupGenerator", g));} - //! \brief Initialize a private key over GF(p) - //! \param params the group parameters - //! \param x the private exponent + /// \brief Initialize a private key over GF(p) + /// \param params the group parameters + /// \param x the private exponent void Initialize(const DL_GroupParameters_IntegerBased ¶ms, const Integer &x) {this->AccessGroupParameters().Initialize(params); this->SetPrivateExponent(x);} - //! \brief Initialize a private key over GF(p) - //! \param p the modulus - //! \param g the generator - //! \param x the private exponent + /// \brief Initialize a private key over GF(p) + /// \param p the modulus + /// \param g the generator + /// \param x the private exponent void Initialize(const Integer &p, const Integer &g, const Integer &x) {this->AccessGroupParameters().Initialize(p, g); this->SetPrivateExponent(x);} - //! \brief Initialize a private key over GF(p) - //! \param p the modulus - //! \param q the subgroup order - //! \param g the generator - //! \param x the private exponent + /// \brief Initialize a private key over GF(p) + /// \param p the modulus + /// \param q the subgroup order + /// \param g the generator + /// \param x the private exponent void Initialize(const Integer &p, const Integer &q, const Integer &g, const Integer &x) {this->AccessGroupParameters().Initialize(p, q, g); this->SetPrivateExponent(x);} }; @@ -574,8 +574,8 @@ public: template DL_PrivateKey_GFP::~DL_PrivateKey_GFP() {} -//! \class DL_SignatureKeys_GFP -//! \brief Discrete Log (DL) signing/verification keys in GF(p) groups +/// \class DL_SignatureKeys_GFP +/// \brief Discrete Log (DL) signing/verification keys in GF(p) groups struct DL_SignatureKeys_GFP { typedef DL_GroupParameters_GFP GroupParameters; @@ -583,8 +583,8 @@ struct DL_SignatureKeys_GFP typedef DL_PrivateKey_GFP PrivateKey; }; -//! \class DL_CryptoKeys_GFP -//! \brief Discrete Log (DL) encryption/decryption keys in GF(p) groups +/// \class DL_CryptoKeys_GFP +/// \brief Discrete Log (DL) encryption/decryption keys in GF(p) groups struct DL_CryptoKeys_GFP { typedef DL_GroupParameters_GFP_DefaultSafePrime GroupParameters; @@ -592,11 +592,11 @@ struct DL_CryptoKeys_GFP typedef DL_PrivateKey_GFP PrivateKey; }; -//! \class DL_PublicKey_GFP_OldFormat -//! \brief Discrete Log (DL) public key in GF(p) groups -//! \tparam BASE GroupParameters derived class -//! \deprecated This implementation uses a non-standard Crypto++ key format. New implementations -//! should use DL_PublicKey_GFP and DL_PrivateKey_GFP +/// \class DL_PublicKey_GFP_OldFormat +/// \brief Discrete Log (DL) public key in GF(p) groups +/// \tparam BASE GroupParameters derived class +/// \deprecated This implementation uses a non-standard Crypto++ key format. New implementations +/// should use DL_PublicKey_GFP and DL_PrivateKey_GFP template class DL_PublicKey_GFP_OldFormat : public BASE { @@ -637,11 +637,11 @@ public: } }; -//! \class DL_PrivateKey_GFP_OldFormat -//! \brief Discrete Log (DL) private key in GF(p) groups -//! \tparam BASE GroupParameters derived class -//! \deprecated This implementation uses a non-standard Crypto++ key format. New implementations -//! should use DL_PublicKey_GFP and DL_PrivateKey_GFP +/// \class DL_PrivateKey_GFP_OldFormat +/// \brief Discrete Log (DL) private key in GF(p) groups +/// \tparam BASE GroupParameters derived class +/// \deprecated This implementation uses a non-standard Crypto++ key format. New implementations +/// should use DL_PublicKey_GFP and DL_PrivateKey_GFP template class DL_PrivateKey_GFP_OldFormat : public BASE { @@ -684,11 +684,11 @@ public: } }; -//! \class GDSA -//! \brief DSA signature scheme -//! \tparam H HashTransformation derived class -//! \sa DSA-1363 -//! \since Crypto++ 1.0 for DSA, Crypto++ 5.6.2 for DSA2 +/// \class GDSA +/// \brief DSA signature scheme +/// \tparam H HashTransformation derived class +/// \sa DSA-1363 +/// \since Crypto++ 1.0 for DSA, Crypto++ 5.6.2 for DSA2 template struct GDSA : public DL_SS< DL_SignatureKeys_GFP, @@ -698,10 +698,10 @@ struct GDSA : public DL_SS< { }; -//! \class NR -//! \brief NR signature scheme -//! \tparam H HashTransformation derived class -//! \sa NR +/// \class NR +/// \brief NR signature scheme +/// \tparam H HashTransformation derived class +/// \sa NR template struct NR : public DL_SS< DL_SignatureKeys_GFP, @@ -711,10 +711,10 @@ struct NR : public DL_SS< { }; -//! \class DL_GroupParameters_DSA -//! \brief DSA group parameters -//! \details These are GF(p) group parameters that are allowed by the DSA standard -//! \sa DL_Keys_DSA +/// \class DL_GroupParameters_DSA +/// \brief DSA group parameters +/// \details These are GF(p) group parameters that are allowed by the DSA standard +/// \sa DL_Keys_DSA class CRYPTOPP_DLL DL_GroupParameters_DSA : public DL_GroupParameters_GFP { public: @@ -735,21 +735,21 @@ public: template class DSA2; -//! \class DL_Keys_DSA -//! \brief DSA keys -//! \sa DL_GroupParameters_DSA +/// \class DL_Keys_DSA +/// \brief DSA keys +/// \sa DL_GroupParameters_DSA struct DL_Keys_DSA { typedef DL_PublicKey_GFP PublicKey; typedef DL_PrivateKey_WithSignaturePairwiseConsistencyTest, DSA2 > PrivateKey; }; -//! \class DSA2 -//! \brief DSA signature scheme -//! \tparam H HashTransformation derived class -//! \details The class is named DSA2 instead of DSA for backwards compatibility because DSA was a non-template class. -//! \sa DSA, as specified in FIPS 186-3 -//! \since Crypto++ 1.0 for DSA, Crypto++ 5.6.2 for DSA2 +/// \class DSA2 +/// \brief DSA signature scheme +/// \tparam H HashTransformation derived class +/// \details The class is named DSA2 instead of DSA for backwards compatibility because DSA was a non-template class. +/// \sa DSA, as specified in FIPS 186-3 +/// \since Crypto++ 1.0 for DSA, Crypto++ 5.6.2 for DSA2 template class DSA2 : public DL_SS< DL_Keys_DSA, @@ -762,11 +762,11 @@ public: static std::string CRYPTOPP_API StaticAlgorithmName() {return "DSA/" + (std::string)H::StaticAlgorithmName();} }; -//! \class DSA_RFC6979 -//! \brief DSA deterministic signature scheme -//! \tparam H HashTransformation derived class -//! \sa DSA-1363 -//! \since Crypto++ 1.0 for DSA, Crypto++ 5.6.2 for DSA2 +/// \class DSA_RFC6979 +/// \brief DSA deterministic signature scheme +/// \tparam H HashTransformation derived class +/// \sa DSA-1363 +/// \since Crypto++ 1.0 for DSA, Crypto++ 5.6.2 for DSA2 template struct DSA_RFC6979 : public DL_SS< DL_SignatureKeys_GFP, @@ -778,27 +778,27 @@ struct DSA_RFC6979 : public DL_SS< static std::string CRYPTOPP_API StaticAlgorithmName() {return std::string("DSA-RFC6979/") + H::StaticAlgorithmName();} }; -//! DSA with SHA-1, typedef'd for backwards compatibility +/// DSA with SHA-1, typedef'd for backwards compatibility typedef DSA2 DSA; CRYPTOPP_DLL_TEMPLATE_CLASS DL_PublicKey_GFP; CRYPTOPP_DLL_TEMPLATE_CLASS DL_PrivateKey_GFP; CRYPTOPP_DLL_TEMPLATE_CLASS DL_PrivateKey_WithSignaturePairwiseConsistencyTest, DSA2 >; -//! \class DL_EncryptionAlgorithm_Xor -//! \brief P1363 based XOR Encryption Method -//! \tparam MAC MessageAuthenticationCode derived class used for MAC computation -//! \tparam DHAES_MODE flag indicating DHAES mode -//! \tparam LABEL_OCTETS flag indicating the label is octet count -//! \details DL_EncryptionAlgorithm_Xor is based on an early P1363 draft, which itself appears to be based on an -//! early Certicom SEC-1 draft (or an early SEC-1 draft was based on a P1363 draft). Crypto++ 4.2 used it in its Integrated -//! Ecryption Schemes with NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. -//! \details If you need this method for Crypto++ 4.2 compatibility, then use the ECIES template class with -//! NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. -//! \details If you need this method for Bouncy Castle 1.54 and Botan 1.11 compatibility, then use the ECIES template class with -//! NoCofactorMultiplication, DHAES_MODE=ture and LABEL_OCTETS=false. -//! \details Bouncy Castle 1.54 and Botan 1.11 compatibility are the default template parameters. -//! \since Crypto++ 4.0 +/// \class DL_EncryptionAlgorithm_Xor +/// \brief P1363 based XOR Encryption Method +/// \tparam MAC MessageAuthenticationCode derived class used for MAC computation +/// \tparam DHAES_MODE flag indicating DHAES mode +/// \tparam LABEL_OCTETS flag indicating the label is octet count +/// \details DL_EncryptionAlgorithm_Xor is based on an early P1363 draft, which itself appears to be based on an +/// early Certicom SEC-1 draft (or an early SEC-1 draft was based on a P1363 draft). Crypto++ 4.2 used it in its Integrated +/// Ecryption Schemes with NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. +/// \details If you need this method for Crypto++ 4.2 compatibility, then use the ECIES template class with +/// NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. +/// \details If you need this method for Bouncy Castle 1.54 and Botan 1.11 compatibility, then use the ECIES template class with +/// NoCofactorMultiplication, DHAES_MODE=ture and LABEL_OCTETS=false. +/// \details Bouncy Castle 1.54 and Botan 1.11 compatibility are the default template parameters. +/// \since Crypto++ 4.0 template class DL_EncryptionAlgorithm_Xor : public DL_SymmetricEncryptionAlgorithm { @@ -881,7 +881,7 @@ public: } }; -//! _ +/// _ template class DL_KeyDerivationAlgorithm_P1363 : public DL_KeyDerivationAlgorithm { @@ -910,40 +910,40 @@ public: } }; -//! \class DLIES -//! \brief Discrete Log Integrated Encryption Scheme -//! \tparam COFACTOR_OPTION cofactor multiplication option -//! \tparam HASH HashTransformation derived class used for key drivation and MAC computation -//! \tparam DHAES_MODE flag indicating if the MAC includes addition context parameters such as the label -//! \tparam LABEL_OCTETS flag indicating if the label size is specified in octets or bits -//! \details DLIES is an Integer based Integrated Encryption Scheme (IES). The scheme combines a Key Encapsulation Method (KEM) -//! with a Data Encapsulation Method (DEM) and a MAC tag. The scheme is -//! IND-CCA2, which is a strong notion of security. -//! You should prefer an Integrated Encryption Scheme over homegrown schemes. -//! \details The library's original implementation is based on an early P1363 draft, which itself appears to be based on an early Certicom -//! SEC-1 draft (or an early SEC-1 draft was based on a P1363 draft). Crypto++ 4.2 used the early draft in its Integrated Ecryption -//! Schemes with NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. -//! \details If you desire an Integrated Encryption Scheme with Crypto++ 4.2 compatibility, then use the DLIES template class with -//! NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. -//! \details If you desire an Integrated Encryption Scheme with Bouncy Castle 1.54 and Botan 1.11 compatibility, then use the DLIES -//! template class with NoCofactorMultiplication, DHAES_MODE=true and LABEL_OCTETS=false. -//! \details The default template parameters ensure compatibility with Bouncy Castle 1.54 and Botan 1.11. The combination of -//! IncompatibleCofactorMultiplication and DHAES_MODE=true is recommended for best efficiency and security. -//! SHA1 is used for compatibility reasons, but it can be changed if desired. SHA-256 or another hash will likely improve the -//! security provided by the MAC. The hash is also used in the key derivation function as a PRF. -//! \details Below is an example of constructing a Crypto++ 4.2 compatible DLIES encryptor and decryptor. -//! 
-//!     AutoSeededRandomPool prng;
-//!     DL_PrivateKey_GFP key;
-//!     key.Initialize(prng, 2048);
-//!
-//!     DLIES::Decryptor decryptor(key);
-//!     DLIES::Encryptor encryptor(decryptor);
-//!
-//! \sa ECIES, Discrete Log Integrated Encryption Scheme (DLIES), -//! Martínez, Encinas, and Ávila's A Survey of the Elliptic -//! Curve Integrated Encryption Schemes -//! \since Crypto++ 4.0, Crypto++ 5.7 for Bouncy Castle and Botan compatibility +/// \class DLIES +/// \brief Discrete Log Integrated Encryption Scheme +/// \tparam COFACTOR_OPTION cofactor multiplication option +/// \tparam HASH HashTransformation derived class used for key drivation and MAC computation +/// \tparam DHAES_MODE flag indicating if the MAC includes addition context parameters such as the label +/// \tparam LABEL_OCTETS flag indicating if the label size is specified in octets or bits +/// \details DLIES is an Integer based Integrated Encryption Scheme (IES). The scheme combines a Key Encapsulation Method (KEM) +/// with a Data Encapsulation Method (DEM) and a MAC tag. The scheme is +/// IND-CCA2, which is a strong notion of security. +/// You should prefer an Integrated Encryption Scheme over homegrown schemes. +/// \details The library's original implementation is based on an early P1363 draft, which itself appears to be based on an early Certicom +/// SEC-1 draft (or an early SEC-1 draft was based on a P1363 draft). Crypto++ 4.2 used the early draft in its Integrated Ecryption +/// Schemes with NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. +/// \details If you desire an Integrated Encryption Scheme with Crypto++ 4.2 compatibility, then use the DLIES template class with +/// NoCofactorMultiplication, DHAES_MODE=false and LABEL_OCTETS=true. +/// \details If you desire an Integrated Encryption Scheme with Bouncy Castle 1.54 and Botan 1.11 compatibility, then use the DLIES +/// template class with NoCofactorMultiplication, DHAES_MODE=true and LABEL_OCTETS=false. +/// \details The default template parameters ensure compatibility with Bouncy Castle 1.54 and Botan 1.11. The combination of +/// IncompatibleCofactorMultiplication and DHAES_MODE=true is recommended for best efficiency and security. +/// SHA1 is used for compatibility reasons, but it can be changed if desired. SHA-256 or another hash will likely improve the +/// security provided by the MAC. The hash is also used in the key derivation function as a PRF. +/// \details Below is an example of constructing a Crypto++ 4.2 compatible DLIES encryptor and decryptor. +/// 
+///     AutoSeededRandomPool prng;
+///     DL_PrivateKey_GFP key;
+///     key.Initialize(prng, 2048);
+///
+///     DLIES::Decryptor decryptor(key);
+///     DLIES::Encryptor encryptor(decryptor);
+///
+/// \sa ECIES, Discrete Log Integrated Encryption Scheme (DLIES), +/// Martínez, Encinas, and Ávila's A Survey of the Elliptic +/// Curve Integrated Encryption Schemes +/// \since Crypto++ 4.0, Crypto++ 5.7 for Bouncy Castle and Botan compatibility template struct DLIES : public DL_ES< diff --git a/gost.h b/gost.h index 851189ce..43f60a8c 100644 --- a/gost.h +++ b/gost.h @@ -1,7 +1,7 @@ // gost.h - originally written and placed in the public domain by Wei Dai -//! \file gost.h -//! \brief Classes for the GIST block cipher +/// \file gost.h +/// \brief Classes for the GIST block cipher #ifndef CRYPTOPP_GOST_H #define CRYPTOPP_GOST_H @@ -11,20 +11,20 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class GOST_Info -//! \brief GOST block cipher information +/// \class GOST_Info +/// \brief GOST block cipher information struct GOST_Info : public FixedBlockSize<8>, public FixedKeyLength<32> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "GOST";} }; -//! \class GOST -//! \brief GOST block cipher -//! \sa GOST +/// \class GOST +/// \brief GOST block cipher +/// \sa GOST class GOST : public GOST_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief GOST block cipher default operation + /// \class Base + /// \brief GOST block cipher default operation class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -40,16 +40,16 @@ class GOST : public GOST_Info, public BlockCipherDocumentation FixedSizeSecBlock m_key; }; - //! \class Enc - //! \brief GOST block cipher encryption operation + /// \class Enc + /// \brief GOST block cipher encryption operation class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \class Dec - //! \brief GOST block cipher decryption operation + /// \class Dec + /// \brief GOST block cipher decryption operation class CRYPTOPP_NO_VTABLE Dec : public Base { public: diff --git a/gzip.h b/gzip.h index f6b9cac0..93c1f6bb 100644 --- a/gzip.h +++ b/gzip.h @@ -1,7 +1,7 @@ // gzip.h - originally written and placed in the public domain by Wei Dai -//! \file gzip.h -//! \brief GZIP compression and decompression (RFC 1952) +/// \file gzip.h +/// \brief GZIP compression and decompression (RFC 1952) #ifndef CRYPTOPP_GZIP_H #define CRYPTOPP_GZIP_H @@ -13,47 +13,47 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Gzip -//! \brief GZIP Compression (RFC 1952) +/// \class Gzip +/// \brief GZIP Compression (RFC 1952) class Gzip : public Deflator { public: - //! \brief Construct a Gzip compressor - //! \param attachment an attached transformation - //! \param deflateLevel the deflate level - //! \param log2WindowSize the window size - //! \param detectUncompressible flag to detect if data is compressible - //! \details detectUncompressible makes it faster to process uncompressible files, but - //! if a file has both compressible and uncompressible parts, it may fail to compress - //! some of the compressible parts. + /// \brief Construct a Gzip compressor + /// \param attachment an attached transformation + /// \param deflateLevel the deflate level + /// \param log2WindowSize the window size + /// \param detectUncompressible flag to detect if data is compressible + /// \details detectUncompressible makes it faster to process uncompressible files, but + /// if a file has both compressible and uncompressible parts, it may fail to compress + /// some of the compressible parts. Gzip(BufferedTransformation *attachment=NULLPTR, unsigned int deflateLevel=DEFAULT_DEFLATE_LEVEL, unsigned int log2WindowSize=DEFAULT_LOG2_WINDOW_SIZE, bool detectUncompressible=true) : Deflator(attachment, deflateLevel, log2WindowSize, detectUncompressible), m_totalLen(0), m_filetime(0) { } - //! \brief Construct a Gzip compressor - //! \param parameters a set of NameValuePairs to initialize this object - //! \param attachment an attached transformation - //! \details Possible parameter names: Log2WindowSize, DeflateLevel, DetectUncompressible + /// \brief Construct a Gzip compressor + /// \param parameters a set of NameValuePairs to initialize this object + /// \param attachment an attached transformation + /// \details Possible parameter names: Log2WindowSize, DeflateLevel, DetectUncompressible Gzip(const NameValuePairs ¶meters, BufferedTransformation *attachment=NULLPTR) : Deflator(parameters, attachment), m_totalLen(0), m_filetime(0) { IsolatedInitialize(parameters); } - //! \param filetime the filetime to set in the header. The application is responsible for setting it. + /// \param filetime the filetime to set in the header. The application is responsible for setting it. void SetFiletime(word32 filetime) { m_filetime = filetime; } - //! \param filename the original filename to set in the header. The application is responsible for setting it. - //! RFC 1952 requires a ISO/IEC 8859-1 encoding. - //! \param throwOnEncodingError if throwOnEncodingError is true, then the filename is checked to ensure it is - //! ISO/IEC 8859-1 encoded. If the filename does not adhere to ISO/IEC 8859-1, then a InvalidDataFormat - //! is thrown. If throwOnEncodingError is false then the filename is not checked. + /// \param filename the original filename to set in the header. The application is responsible for setting it. + /// RFC 1952 requires a ISO/IEC 8859-1 encoding. + /// \param throwOnEncodingError if throwOnEncodingError is true, then the filename is checked to ensure it is + /// ISO/IEC 8859-1 encoded. If the filename does not adhere to ISO/IEC 8859-1, then a InvalidDataFormat + /// is thrown. If throwOnEncodingError is false then the filename is not checked. void SetFilename(const std::string& filename, bool throwOnEncodingError = false); - //! \param comment the comment to set in the header. The application is responsible for setting it. - //! RFC 1952 requires a ISO/IEC 8859-1 encoding. - //! \param throwOnEncodingError if throwOnEncodingError is true, then the comment is checked to ensure it is - //! ISO/IEC 8859-1 encoded. If the comment does not adhere to ISO/IEC 8859-1, then a InvalidDataFormat - //! is thrown. If throwOnEncodingError is false then the comment is not checked. + /// \param comment the comment to set in the header. The application is responsible for setting it. + /// RFC 1952 requires a ISO/IEC 8859-1 encoding. + /// \param throwOnEncodingError if throwOnEncodingError is true, then the comment is checked to ensure it is + /// ISO/IEC 8859-1 encoded. If the comment does not adhere to ISO/IEC 8859-1, then a InvalidDataFormat + /// is thrown. If throwOnEncodingError is false then the comment is not checked. void SetComment(const std::string& comment, bool throwOnEncodingError = false); void IsolatedInitialize(const NameValuePairs ¶meters); @@ -77,54 +77,54 @@ protected: std::string m_comment; }; -//! \class Gunzip -//! \brief GZIP Decompression (RFC 1952) +/// \class Gunzip +/// \brief GZIP Decompression (RFC 1952) class Gunzip : public Inflator { public: typedef Inflator::Err Err; - //! \class HeaderErr - //! \brief Exception thrown when a header decoding error occurs + /// \class HeaderErr + /// \brief Exception thrown when a header decoding error occurs class HeaderErr : public Err {public: HeaderErr() : Err(INVALID_DATA_FORMAT, "Gunzip: header decoding error") {}}; - //! \class TailErr - //! \brief Exception thrown when the tail is too short + /// \class TailErr + /// \brief Exception thrown when the tail is too short class TailErr : public Err {public: TailErr() : Err(INVALID_DATA_FORMAT, "Gunzip: tail too short") {}}; - //! \class CrcErr - //! \brief Exception thrown when a CRC error occurs + /// \class CrcErr + /// \brief Exception thrown when a CRC error occurs class CrcErr : public Err {public: CrcErr() : Err(DATA_INTEGRITY_CHECK_FAILED, "Gunzip: CRC check error") {}}; - //! \class LengthErr - //! \brief Exception thrown when a length error occurs + /// \class LengthErr + /// \brief Exception thrown when a length error occurs class LengthErr : public Err {public: LengthErr() : Err(DATA_INTEGRITY_CHECK_FAILED, "Gunzip: length check error") {}}; - //! \brief Construct a Gunzip decompressor - //! \param attachment an attached transformation - //! \param repeat decompress multiple compressed streams in series - //! \param autoSignalPropagation 0 to turn off MessageEnd signal + /// \brief Construct a Gunzip decompressor + /// \param attachment an attached transformation + /// \param repeat decompress multiple compressed streams in series + /// \param autoSignalPropagation 0 to turn off MessageEnd signal Gunzip(BufferedTransformation *attachment = NULLPTR, bool repeat = false, int autoSignalPropagation = -1); - //! \return the filetime of the stream as set in the header. The application is responsible for setting it on the decompressed file. + /// \return the filetime of the stream as set in the header. The application is responsible for setting it on the decompressed file. word32 GetFiletime() const { return m_filetime; } - //! \return the filename of the stream as set in the header. The application is responsible for setting it on the decompressed file. - //! \param throwOnEncodingError if throwOnEncodingError is true, then the filename is checked to ensure it is - //! ISO/IEC 8859-1 encoded. If the filename does not adhere to ISO/IEC 8859-1, then a InvalidDataFormat is thrown. - //! If throwOnEncodingError is false then the filename is not checked. + /// \return the filename of the stream as set in the header. The application is responsible for setting it on the decompressed file. + /// \param throwOnEncodingError if throwOnEncodingError is true, then the filename is checked to ensure it is + /// ISO/IEC 8859-1 encoded. If the filename does not adhere to ISO/IEC 8859-1, then a InvalidDataFormat is thrown. + /// If throwOnEncodingError is false then the filename is not checked. const std::string& GetFilename(bool throwOnEncodingError = false) const; - //! \return the comment of the stream as set in the header. - //! \param throwOnEncodingError if throwOnEncodingError is true, then the comment is checked to ensure it is - //! ISO/IEC 8859-1 encoded. If the comment does not adhere to ISO/IEC 8859-1, then a InvalidDataFormat is thrown. - //! If throwOnEncodingError is false then the comment is not checked. + /// \return the comment of the stream as set in the header. + /// \param throwOnEncodingError if throwOnEncodingError is true, then the comment is checked to ensure it is + /// ISO/IEC 8859-1 encoded. If the comment does not adhere to ISO/IEC 8859-1, then a InvalidDataFormat is thrown. + /// If throwOnEncodingError is false then the comment is not checked. const std::string& GetComment(bool throwOnEncodingError = false) const; protected: enum { - //! \brief First header magic value + /// \brief First header magic value MAGIC1=0x1f, - //! \brief Second header magic value + /// \brief Second header magic value MAGIC2=0x8b, - //! \brief Deflated flag + /// \brief Deflated flag DEFLATED=8 }; diff --git a/hex.h b/hex.h index 008a6dbb..ba6ee98f 100644 --- a/hex.h +++ b/hex.h @@ -1,7 +1,7 @@ // hex.h - originally written and placed in the public domain by Wei Dai -//! \file hex.h -//! \brief Classes for HexEncoder and HexDecoder +/// \file hex.h +/// \brief Classes for HexEncoder and HexDecoder #ifndef CRYPTOPP_HEX_H #define CRYPTOPP_HEX_H @@ -11,17 +11,17 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class HexEncoder -//! \brief Converts given data to base 16 +/// \class HexEncoder +/// \brief Converts given data to base 16 class CRYPTOPP_DLL HexEncoder : public SimpleProxyFilter { public: - //! \brief Construct a HexEncoder - //! \param attachment a BufferedTrasformation to attach to this object - //! \param uppercase a flag indicating uppercase output - //! \param groupSize the size of the output grouping - //! \param separator the separator to use between groups - //! \param terminator the terminator append after processing + /// \brief Construct a HexEncoder + /// \param attachment a BufferedTrasformation to attach to this object + /// \param uppercase a flag indicating uppercase output + /// \param groupSize the size of the output grouping + /// \param separator the separator to use between groups + /// \param terminator the terminator append after processing HexEncoder(BufferedTransformation *attachment = NULLPTR, bool uppercase = true, int groupSize = 0, const std::string &separator = ":", const std::string &terminator = "") : SimpleProxyFilter(new BaseN_Encoder(new Grouper), attachment) { @@ -31,13 +31,13 @@ public: void IsolatedInitialize(const NameValuePairs ¶meters); }; -//! \class HexDecoder -//! \brief Decode base 16 data back to bytes +/// \class HexDecoder +/// \brief Decode base 16 data back to bytes class CRYPTOPP_DLL HexDecoder : public BaseN_Decoder { public: - //! \brief Construct a HexDecoder - //! \param attachment a BufferedTrasformation to attach to this object + /// \brief Construct a HexDecoder + /// \param attachment a BufferedTrasformation to attach to this object HexDecoder(BufferedTransformation *attachment = NULLPTR) : BaseN_Decoder(GetDefaultDecodingLookupArray(), 4, attachment) {} diff --git a/hkdf.h b/hkdf.h index a77d9876..00217c98 100644 --- a/hkdf.h +++ b/hkdf.h @@ -1,8 +1,8 @@ // hkdf.h - written and placed in public domain by Jeffrey Walton. -//! \file hkdf.h -//! \brief Classes for HKDF from RFC 5869 -//! \since Crypto++ 5.6.3 +/// \file hkdf.h +/// \brief Classes for HKDF from RFC 5869 +/// \since Crypto++ 5.6.3 #ifndef CRYPTOPP_HASH_KEY_DERIVATION_FUNCTION_H #define CRYPTOPP_HASH_KEY_DERIVATION_FUNCTION_H @@ -14,24 +14,24 @@ NAMESPACE_BEGIN(CryptoPP) -//! abstract base class for key derivation function +/// abstract base class for key derivation function class KeyDerivationFunction { public: - //! maximum number of bytes which can be produced under a secuirty context + /// maximum number of bytes which can be produced under a secuirty context virtual size_t MaxDerivedKeyLength() const =0; virtual bool Usesinfo() const =0; - //! derive a key from secret + /// derive a key from secret virtual unsigned int DeriveKey(byte *derived, size_t derivedLen, const byte *secret, size_t secretLen, const byte *salt, size_t saltLen, const byte* info=NULLPTR, size_t infoLen=0) const =0; virtual ~KeyDerivationFunction() {} }; -//! \brief Extract-and-Expand Key Derivation Function (HKDF) -//! \tparam T HashTransformation class -//! \sa Cryptographic Extraction and Key Derivation: The HKDF Scheme -//! and HMAC-based Extract-and-Expand Key Derivation Function (HKDF) -//! \since Crypto++ 5.6.3 +/// \brief Extract-and-Expand Key Derivation Function (HKDF) +/// \tparam T HashTransformation class +/// \sa Cryptographic Extraction and Key Derivation: The HKDF Scheme +/// and HMAC-based Extract-and-Expand Key Derivation Function (HKDF) +/// \since Crypto++ 5.6.3 template class HKDF : public KeyDerivationFunction { diff --git a/hmac.h b/hmac.h index f4f60f7b..8304df83 100644 --- a/hmac.h +++ b/hmac.h @@ -1,7 +1,7 @@ // hmac.h - originally written and placed in the public domain by Wei Dai -//! \file hmac.h -//! \brief Classes for HMAC message authentication codes +/// \file hmac.h +/// \brief Classes for HMAC message authentication codes #ifndef CRYPTOPP_HMAC_H #define CRYPTOPP_HMAC_H @@ -11,13 +11,13 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class HMAC_Base -//! \brief HMAC information -//! \details HMAC_Base derives from VariableKeyLength and MessageAuthenticationCode +/// \class HMAC_Base +/// \brief HMAC information +/// \details HMAC_Base derives from VariableKeyLength and MessageAuthenticationCode class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE HMAC_Base : public VariableKeyLength<16, 0, INT_MAX>, public MessageAuthenticationCode { public: - //! \brief Construct a HMAC_Base + /// \brief Construct a HMAC_Base HMAC_Base() : m_innerHashKeyed(false) {} void UncheckedSetKey(const byte *userKey, unsigned int keylength, const NameValuePairs ¶ms); @@ -40,12 +40,12 @@ private: bool m_innerHashKeyed; }; -//! \class HMAC -//! \brief HMAC -//! \tparam T HashTransformation derived class -//! \details HMAC derives from MessageAuthenticationCodeImpl. It calculates the HMAC using -//! HMAC(K, text) = H(K XOR opad, H(K XOR ipad, text)). -//! \sa HMAC +/// \class HMAC +/// \brief HMAC +/// \tparam T HashTransformation derived class +/// \details HMAC derives from MessageAuthenticationCodeImpl. It calculates the HMAC using +/// HMAC(K, text) = H(K XOR opad, H(K XOR ipad, text)). +/// \sa HMAC template class HMAC : public MessageAuthenticationCodeImpl > { @@ -53,11 +53,11 @@ public: CRYPTOPP_CONSTANT(DIGESTSIZE=T::DIGESTSIZE) CRYPTOPP_CONSTANT(BLOCKSIZE=T::BLOCKSIZE) - //! \brief Construct a HMAC + /// \brief Construct a HMAC HMAC() {} - //! \brief Construct a HMAC - //! \param key the HMAC key - //! \param length the size of the HMAC key + /// \brief Construct a HMAC + /// \param key the HMAC key + /// \param length the size of the HMAC key HMAC(const byte *key, size_t length=HMAC_Base::DEFAULT_KEYLENGTH) {this->SetKey(key, length);} diff --git a/hmqv.h b/hmqv.h index c25e5f1b..870cbfad 100644 --- a/hmqv.h +++ b/hmqv.h @@ -4,9 +4,9 @@ #ifndef CRYPTOPP_HMQV_H #define CRYPTOPP_HMQV_H -//! \file hmqv.h -//! \brief Classes for Hashed Menezes-Qu-Vanstone key agreement in GF(p) -//! \since Crypto++ 5.6.4 +/// \file hmqv.h +/// \brief Classes for Hashed Menezes-Qu-Vanstone key agreement in GF(p) +/// \since Crypto++ 5.6.4 #include "gfpcrypt.h" #include "algebra.h" @@ -14,11 +14,11 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Hashed Menezes-Qu-Vanstone in GF(p) -//! \details This implementation follows Hugo Krawczyk's HMQV: A High-Performance -//! Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided. -//! \sa MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain -//! \since Crypto++ 5.6.4 +/// \brief Hashed Menezes-Qu-Vanstone in GF(p) +/// \details This implementation follows Hugo Krawczyk's HMQV: A High-Performance +/// Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided. +/// \sa MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain +/// \since Crypto++ 5.6.4 template class HMQV_Domain: public AuthenticatedKeyAgreementDomain { @@ -65,14 +65,14 @@ public: CryptoParameters & AccessCryptoParameters(){return AccessAbstractGroupParameters();} - //! return length of agreed value produced + /// return length of agreed value produced unsigned int AgreedValueLength() const {return GetAbstractGroupParameters().GetEncodedElementSize(false);} - //! return length of static private keys in this domain + /// return length of static private keys in this domain unsigned int StaticPrivateKeyLength() const {return GetAbstractGroupParameters().GetSubgroupOrder().ByteCount();} - //! return length of static public keys in this domain + /// return length of static public keys in this domain unsigned int StaticPublicKeyLength() const{return GetAbstractGroupParameters().GetEncodedElementSize(true);} - //! generate static private key + /// generate static private key /*! \pre size of privateKey == PrivateStaticKeyLength() */ void GenerateStaticPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const { @@ -80,7 +80,7 @@ public: x.Encode(privateKey, StaticPrivateKeyLength()); } - //! generate static public key + /// generate static public key /*! \pre size of publicKey == PublicStaticKeyLength() */ void GenerateStaticPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const { @@ -94,7 +94,7 @@ public: unsigned int EphemeralPrivateKeyLength() const {return StaticPrivateKeyLength() + StaticPublicKeyLength();} unsigned int EphemeralPublicKeyLength() const{return StaticPublicKeyLength();} - //! return length of ephemeral private keys in this domain + /// return length of ephemeral private keys in this domain void GenerateEphemeralPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const { const DL_GroupParameters ¶ms = GetAbstractGroupParameters(); @@ -104,14 +104,14 @@ public: params.EncodeElement(true, y, privateKey+StaticPrivateKeyLength()); } - //! return length of ephemeral public keys in this domain + /// return length of ephemeral public keys in this domain void GenerateEphemeralPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const { CRYPTOPP_UNUSED(rng); memcpy(publicKey, privateKey+StaticPrivateKeyLength(), EphemeralPublicKeyLength()); } - //! derive agreed value from your private keys and couterparty's public keys, return false in case of failure + /// derive agreed value from your private keys and couterparty's public keys, return false in case of failure /*! \note The ephemeral public key will always be validated. If you have previously validated the static public key, use validateStaticOtherPublicKey=false to save time. \pre size of agreedValue == AgreedValueLength() @@ -298,11 +298,11 @@ private: KeyAgreementRole m_role; }; -//! \brief Hashed Menezes-Qu-Vanstone in GF(p) -//! \details This implementation follows Hugo Krawczyk's HMQV: A High-Performance -//! Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided. -//! \sa HMQV, MQV_Domain, FHMQV_Domain, AuthenticatedKeyAgreementDomain -//! \since Crypto++ 5.6.4 +/// \brief Hashed Menezes-Qu-Vanstone in GF(p) +/// \details This implementation follows Hugo Krawczyk's HMQV: A High-Performance +/// Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided. +/// \sa HMQV, MQV_Domain, FHMQV_Domain, AuthenticatedKeyAgreementDomain +/// \since Crypto++ 5.6.4 typedef HMQV_Domain HMQV; NAMESPACE_END diff --git a/hrtimer.h b/hrtimer.h index 88c2e538..9507d5bd 100644 --- a/hrtimer.h +++ b/hrtimer.h @@ -15,8 +15,8 @@ NAMESPACE_BEGIN(CryptoPP) typedef clock_t TimerWord; #endif -//! \class TimerBase -//! \brief Base class for timers +/// \class TimerBase +/// \brief Base class for timers class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE TimerBase { public: @@ -40,11 +40,11 @@ private: TimerWord m_start, m_last; }; -//! \class ThreadUserTimer -//! \brief Measure CPU time spent executing instructions of this thread (if supported by OS) -//! \note ThreadUserTimer only works correctly on Windows NT or later desktops and servers. -//! On Unix-based it reports process time. On Windows Phone and Windows Store it reports wall -//! clock time with performance counter precision. On all others it reports wall clock time. +/// \class ThreadUserTimer +/// \brief Measure CPU time spent executing instructions of this thread (if supported by OS) +/// \note ThreadUserTimer only works correctly on Windows NT or later desktops and servers. +/// On Unix-based it reports process time. On Windows Phone and Windows Store it reports wall +/// clock time with performance counter precision. On all others it reports wall clock time. class ThreadUserTimer : public TimerBase { public: @@ -53,7 +53,7 @@ public: TimerWord TicksPerSecond(); }; -//! high resolution timer +/// high resolution timer class CRYPTOPP_DLL Timer : public TimerBase { public: diff --git a/ida.h b/ida.h index a1e29067..603e3f2c 100644 --- a/ida.h +++ b/ida.h @@ -1,7 +1,7 @@ // ida.h - originally written and placed in the public domain by Wei Dai -//! \file ida.h -//! \brief Classes for Rabin's Information Dispersal and Shamir's Secret Sharing algorithms +/// \file ida.h +/// \brief Classes for Rabin's Information Dispersal and Shamir's Secret Sharing algorithms #ifndef CRYPTOPP_IDA_H #define CRYPTOPP_IDA_H @@ -16,9 +16,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RawIDA -//! \brief Secret sharing and information dispersal base class -//! \since Crypto++ 1.0 +/// \class RawIDA +/// \brief Secret sharing and information dispersal base class +/// \since Crypto++ 1.0 class RawIDA : public AutoSignaling > > { public: @@ -63,15 +63,15 @@ protected: SecBlock m_u, m_w, m_y; }; -//! \class SecretSharing -//! \brief Shamir's Secret Sharing Algorithm -//! \details SecretSharing is a variant of Shamir's secret sharing algorithm -//! \sa SecretRecovery, SecretRecovery, InformationDispersal, InformationRecovery -//! \since Crypto++ 1.0 +/// \class SecretSharing +/// \brief Shamir's Secret Sharing Algorithm +/// \details SecretSharing is a variant of Shamir's secret sharing algorithm +/// \sa SecretRecovery, SecretRecovery, InformationDispersal, InformationRecovery +/// \since Crypto++ 1.0 class SecretSharing : public CustomFlushPropagation { public: - //! \brief Construct a SecretSharing + /// \brief Construct a SecretSharing SecretSharing(RandomNumberGenerator &rng, int threshold, int nShares, BufferedTransformation *attachment=NULLPTR, bool addPadding=true) : m_rng(rng), m_ida(new OutputProxy(*this, true)) { @@ -89,15 +89,15 @@ protected: bool m_pad; }; -//! \class SecretRecovery -//! \brief Shamir's Secret Sharing Algorithm -//! \details SecretSharing is a variant of Shamir's secret sharing algorithm -//! \sa SecretRecovery, SecretRecovery, InformationDispersal, InformationRecovery -//! \since Crypto++ 1.0 +/// \class SecretRecovery +/// \brief Shamir's Secret Sharing Algorithm +/// \details SecretSharing is a variant of Shamir's secret sharing algorithm +/// \sa SecretRecovery, SecretRecovery, InformationDispersal, InformationRecovery +/// \since Crypto++ 1.0 class SecretRecovery : public RawIDA { public: - //! \brief Construct a SecretRecovery + /// \brief Construct a SecretRecovery SecretRecovery(int threshold, BufferedTransformation *attachment=NULLPTR, bool removePadding=true) : RawIDA(attachment) {IsolatedInitialize(MakeParameters("RecoveryThreshold", threshold)("RemovePadding", removePadding));} @@ -113,15 +113,15 @@ protected: /// a variant of Rabin's Information Dispersal Algorithm -//! \class InformationDispersal -//! \brief Rabin's Information Dispersal Algorithm -//! \details InformationDispersal is a variant of Rabin's information dispersal algorithm -//! \sa SecretRecovery, SecretRecovery, InformationDispersal, InformationRecovery -//! \since Crypto++ 1.0 +/// \class InformationDispersal +/// \brief Rabin's Information Dispersal Algorithm +/// \details InformationDispersal is a variant of Rabin's information dispersal algorithm +/// \sa SecretRecovery, SecretRecovery, InformationDispersal, InformationRecovery +/// \since Crypto++ 1.0 class InformationDispersal : public CustomFlushPropagation { public: - //! \brief Construct a InformationDispersal + /// \brief Construct a InformationDispersal InformationDispersal(int threshold, int nShares, BufferedTransformation *attachment=NULLPTR, bool addPadding=true) : m_ida(new OutputProxy(*this, true)), m_pad(false), m_nextChannel(0) { @@ -139,15 +139,15 @@ protected: unsigned int m_nextChannel; }; -//! \class InformationRecovery -//! \brief Rabin's Information Dispersal Algorithm -//! \details InformationDispersal is a variant of Rabin's information dispersal algorithm -//! \sa SecretRecovery, SecretRecovery, InformationDispersal, InformationRecovery -//! \since Crypto++ 1.0 +/// \class InformationRecovery +/// \brief Rabin's Information Dispersal Algorithm +/// \details InformationDispersal is a variant of Rabin's information dispersal algorithm +/// \sa SecretRecovery, SecretRecovery, InformationDispersal, InformationRecovery +/// \since Crypto++ 1.0 class InformationRecovery : public RawIDA { public: - //! \brief Construct a InformationRecovery + /// \brief Construct a InformationRecovery InformationRecovery(int threshold, BufferedTransformation *attachment=NULLPTR, bool removePadding=true) : RawIDA(attachment), m_pad(false) {IsolatedInitialize(MakeParameters("RecoveryThreshold", threshold)("RemovePadding", removePadding));} diff --git a/idea.h b/idea.h index 9957c9c9..8ca362e3 100644 --- a/idea.h +++ b/idea.h @@ -1,7 +1,7 @@ // idea.h - originally written and placed in the public domain by Wei Dai -//! \file idea.h -//! \brief Classes for the IDEA block cipher +/// \file idea.h +/// \brief Classes for the IDEA block cipher #ifndef CRYPTOPP_IDEA_H #define CRYPTOPP_IDEA_H @@ -11,18 +11,18 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class IDEA_Info -//! \brief IDEA block cipher information -//! \since Crypto++ 1.0 +/// \class IDEA_Info +/// \brief IDEA block cipher information +/// \since Crypto++ 1.0 struct IDEA_Info : public FixedBlockSize<8>, public FixedKeyLength<16>, public FixedRounds<8> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "IDEA";} }; -//! \class IDEA -//! \brief IDEA block cipher -//! \sa IDEA -//! \since Crypto++ 1.0 +/// \class IDEA +/// \brief IDEA block cipher +/// \sa IDEA +/// \since Crypto++ 1.0 class IDEA : public IDEA_Info, public BlockCipherDocumentation { public: // made public for internal purposes diff --git a/integer.h b/integer.h index 3f8bb9c5..864cdecb 100644 --- a/integer.h +++ b/integer.h @@ -1,17 +1,17 @@ // integer.h - originally written and placed in the public domain by Wei Dai -//! \file integer.h -//! \brief Multiple precision integer with arithmetic operations -//! \details The Integer class can represent positive and negative integers -//! with absolute value less than (256**sizeof(word))(256**sizeof(int)). -//! \details Internally, the library uses a sign magnitude representation, and the class -//! has two data members. The first is a IntegerSecBlock (a SecBlock) and it is -//! used to hold the representation. The second is a Sign (an enumeration), and it is -//! used to track the sign of the Integer. -//! \details For details on how the Integer class initializes its function pointers using -//! InitializeInteger and how it creates Integer::Zero(), Integer::One(), and -//! Integer::Two(), then see the comments at the top of integer.cpp. -//! \since Crypto++ 1.0 +/// \file integer.h +/// \brief Multiple precision integer with arithmetic operations +/// \details The Integer class can represent positive and negative integers +/// with absolute value less than (256**sizeof(word))(256**sizeof(int)). +/// \details Internally, the library uses a sign magnitude representation, and the class +/// has two data members. The first is a IntegerSecBlock (a SecBlock) and it is +/// used to hold the representation. The second is a Sign (an enumeration), and it is +/// used to track the sign of the Integer. +/// \details For details on how the Integer class initializes its function pointers using +/// InitializeInteger and how it creates Integer::Zero(), Integer::One(), and +/// Integer::Two(), then see the comments at the top of integer.cpp. +/// \since Crypto++ 1.0 #ifndef CRYPTOPP_INTEGER_H #define CRYPTOPP_INTEGER_H @@ -24,8 +24,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \struct InitializeInteger -//! \brief Performs static initialization of the Integer class +/// \struct InitializeInteger +/// \brief Performs static initialization of the Integer class struct InitializeInteger { InitializeInteger(); @@ -34,417 +34,417 @@ struct InitializeInteger // Always align, http://github.com/weidai11/cryptopp/issues/256 typedef SecBlock > IntegerSecBlock; -//! \brief Multiple precision integer with arithmetic operations -//! \details The Integer class can represent positive and negative integers -//! with absolute value less than (256**sizeof(word))(256**sizeof(int)). -//! \details Internally, the library uses a sign magnitude representation, and the class -//! has two data members. The first is a IntegerSecBlock (a SecBlock) and it is -//! used to hold the representation. The second is a Sign (an enumeration), and it is -//! used to track the sign of the Integer. -//! \details For details on how the Integer class initializes its function pointers using -//! InitializeInteger and how it creates Integer::Zero(), Integer::One(), and -//! Integer::Two(), then see the comments at the top of integer.cpp. -//! \since Crypto++ 1.0 -//! \nosubgrouping +/// \brief Multiple precision integer with arithmetic operations +/// \details The Integer class can represent positive and negative integers +/// with absolute value less than (256**sizeof(word))(256**sizeof(int)). +/// \details Internally, the library uses a sign magnitude representation, and the class +/// has two data members. The first is a IntegerSecBlock (a SecBlock) and it is +/// used to hold the representation. The second is a Sign (an enumeration), and it is +/// used to track the sign of the Integer. +/// \details For details on how the Integer class initializes its function pointers using +/// InitializeInteger and how it creates Integer::Zero(), Integer::One(), and +/// Integer::Two(), then see the comments at the top of integer.cpp. +/// \since Crypto++ 1.0 +/// \nosubgrouping class CRYPTOPP_DLL Integer : private InitializeInteger, public ASN1Object { public: - //! \name ENUMS, EXCEPTIONS, and TYPEDEFS + /// \name ENUMS, EXCEPTIONS, and TYPEDEFS //@{ - //! \brief Exception thrown when division by 0 is encountered + /// \brief Exception thrown when division by 0 is encountered class DivideByZero : public Exception { public: DivideByZero() : Exception(OTHER_ERROR, "Integer: division by zero") {} }; - //! \brief Exception thrown when a random number cannot be found that - //! satisfies the condition + /// \brief Exception thrown when a random number cannot be found that + /// satisfies the condition class RandomNumberNotFound : public Exception { public: RandomNumberNotFound() : Exception(OTHER_ERROR, "Integer: no integer satisfies the given parameters") {} }; - //! \enum Sign - //! \brief Used internally to represent the integer - //! \details Sign is used internally to represent the integer. It is also used in a few API functions. - //! \sa SetPositive(), SetNegative(), Signedness + /// \enum Sign + /// \brief Used internally to represent the integer + /// \details Sign is used internally to represent the integer. It is also used in a few API functions. + /// \sa SetPositive(), SetNegative(), Signedness enum Sign { - //! \brief the value is positive or 0 + /// \brief the value is positive or 0 POSITIVE=0, - //! \brief the value is negative + /// \brief the value is negative NEGATIVE=1}; - //! \enum Signedness - //! \brief Used when importing and exporting integers - //! \details Signedness is usually used in API functions. - //! \sa Sign + /// \enum Signedness + /// \brief Used when importing and exporting integers + /// \details Signedness is usually used in API functions. + /// \sa Sign enum Signedness { - //! \brief an unsigned value + /// \brief an unsigned value UNSIGNED, - //! \brief a signed value + /// \brief a signed value SIGNED}; - //! \enum RandomNumberType - //! \brief Properties of a random integer + /// \enum RandomNumberType + /// \brief Properties of a random integer enum RandomNumberType { - //! \brief a number with no special properties + /// \brief a number with no special properties ANY, - //! \brief a number which is probabilistically prime + /// \brief a number which is probabilistically prime PRIME}; //@} - //! \name CREATORS + /// \name CREATORS //@{ - //! \brief Creates the zero integer + /// \brief Creates the zero integer Integer(); - //! copy constructor + /// copy constructor Integer(const Integer& t); - //! \brief Convert from signed long + /// \brief Convert from signed long Integer(signed long value); - //! \brief Convert from lword - //! \param sign enumeration indicating Sign - //! \param value the long word + /// \brief Convert from lword + /// \param sign enumeration indicating Sign + /// \param value the long word Integer(Sign sign, lword value); - //! \brief Convert from two words - //! \param sign enumeration indicating Sign - //! \param highWord the high word - //! \param lowWord the low word + /// \brief Convert from two words + /// \param sign enumeration indicating Sign + /// \param highWord the high word + /// \param lowWord the low word Integer(Sign sign, word highWord, word lowWord); - //! \brief Convert from a C-string - //! \param str C-string value - //! \param order the ByteOrder of the string to be processed - //! \details \p str can be in base 2, 8, 10, or 16. Base is determined by a case - //! insensitive suffix of 'h', 'o', or 'b'. No suffix means base 10. - //! \details Byte order was added at Crypto++ 5.7 to allow use of little-endian - //! integers with curve25519, Poly1305 and Microsoft CAPI. + /// \brief Convert from a C-string + /// \param str C-string value + /// \param order the ByteOrder of the string to be processed + /// \details \p str can be in base 2, 8, 10, or 16. Base is determined by a case + /// insensitive suffix of 'h', 'o', or 'b'. No suffix means base 10. + /// \details Byte order was added at Crypto++ 5.7 to allow use of little-endian + /// integers with curve25519, Poly1305 and Microsoft CAPI. explicit Integer(const char *str, ByteOrder order = BIG_ENDIAN_ORDER); - //! \brief Convert from a wide C-string - //! \param str wide C-string value - //! \param order the ByteOrder of the string to be processed - //! \details \p str can be in base 2, 8, 10, or 16. Base is determined by a case - //! insensitive suffix of 'h', 'o', or 'b'. No suffix means base 10. - //! \details Byte order was added at Crypto++ 5.7 to allow use of little-endian - //! integers with curve25519, Poly1305 and Microsoft CAPI. + /// \brief Convert from a wide C-string + /// \param str wide C-string value + /// \param order the ByteOrder of the string to be processed + /// \details \p str can be in base 2, 8, 10, or 16. Base is determined by a case + /// insensitive suffix of 'h', 'o', or 'b'. No suffix means base 10. + /// \details Byte order was added at Crypto++ 5.7 to allow use of little-endian + /// integers with curve25519, Poly1305 and Microsoft CAPI. explicit Integer(const wchar_t *str, ByteOrder order = BIG_ENDIAN_ORDER); - //! \brief Convert from a big-endian byte array - //! \param encodedInteger big-endian byte array - //! \param byteCount length of the byte array - //! \param sign enumeration indicating Signedness - //! \param order the ByteOrder of the array to be processed - //! \details Byte order was added at Crypto++ 5.7 to allow use of little-endian - //! integers with curve25519, Poly1305 and Microsoft CAPI. + /// \brief Convert from a big-endian byte array + /// \param encodedInteger big-endian byte array + /// \param byteCount length of the byte array + /// \param sign enumeration indicating Signedness + /// \param order the ByteOrder of the array to be processed + /// \details Byte order was added at Crypto++ 5.7 to allow use of little-endian + /// integers with curve25519, Poly1305 and Microsoft CAPI. Integer(const byte *encodedInteger, size_t byteCount, Signedness sign=UNSIGNED, ByteOrder order = BIG_ENDIAN_ORDER); - //! \brief Convert from a big-endian array - //! \param bt BufferedTransformation object with big-endian byte array - //! \param byteCount length of the byte array - //! \param sign enumeration indicating Signedness - //! \param order the ByteOrder of the data to be processed - //! \details Byte order was added at Crypto++ 5.7 to allow use of little-endian - //! integers with curve25519, Poly1305 and Microsoft CAPI. + /// \brief Convert from a big-endian array + /// \param bt BufferedTransformation object with big-endian byte array + /// \param byteCount length of the byte array + /// \param sign enumeration indicating Signedness + /// \param order the ByteOrder of the data to be processed + /// \details Byte order was added at Crypto++ 5.7 to allow use of little-endian + /// integers with curve25519, Poly1305 and Microsoft CAPI. Integer(BufferedTransformation &bt, size_t byteCount, Signedness sign=UNSIGNED, ByteOrder order = BIG_ENDIAN_ORDER); - //! \brief Convert from a BER encoded byte array - //! \param bt BufferedTransformation object with BER encoded byte array + /// \brief Convert from a BER encoded byte array + /// \param bt BufferedTransformation object with BER encoded byte array explicit Integer(BufferedTransformation &bt); - //! \brief Create a random integer - //! \param rng RandomNumberGenerator used to generate material - //! \param bitCount the number of bits in the resulting integer - //! \details The random integer created is uniformly distributed over [0, 2bitCount]. + /// \brief Create a random integer + /// \param rng RandomNumberGenerator used to generate material + /// \param bitCount the number of bits in the resulting integer + /// \details The random integer created is uniformly distributed over [0, 2bitCount]. Integer(RandomNumberGenerator &rng, size_t bitCount); - //! \brief Integer representing 0 - //! \returns an Integer representing 0 - //! \details Zero() avoids calling constructors for frequently used integers + /// \brief Integer representing 0 + /// \returns an Integer representing 0 + /// \details Zero() avoids calling constructors for frequently used integers static const Integer & CRYPTOPP_API Zero(); - //! \brief Integer representing 1 - //! \returns an Integer representing 1 - //! \details One() avoids calling constructors for frequently used integers + /// \brief Integer representing 1 + /// \returns an Integer representing 1 + /// \details One() avoids calling constructors for frequently used integers static const Integer & CRYPTOPP_API One(); - //! \brief Integer representing 2 - //! \returns an Integer representing 2 - //! \details Two() avoids calling constructors for frequently used integers + /// \brief Integer representing 2 + /// \returns an Integer representing 2 + /// \details Two() avoids calling constructors for frequently used integers static const Integer & CRYPTOPP_API Two(); - //! \brief Create a random integer of special form - //! \param rng RandomNumberGenerator used to generate material - //! \param min the minimum value - //! \param max the maximum value - //! \param rnType RandomNumberType to specify the type - //! \param equiv the equivalence class based on the parameter \p mod - //! \param mod the modulus used to reduce the equivalence class - //! \throw RandomNumberNotFound if the set is empty. - //! \details Ideally, the random integer created should be uniformly distributed - //! over {x | min \<= x \<= max and \p x is of rnType and x \% mod == equiv}. - //! However the actual distribution may not be uniform because sequential - //! search is used to find an appropriate number from a random starting - //! point. - //! \details May return (with very small probability) a pseudoprime when a prime - //! is requested and max \> lastSmallPrime*lastSmallPrime. \p lastSmallPrime - //! is declared in nbtheory.h. + /// \brief Create a random integer of special form + /// \param rng RandomNumberGenerator used to generate material + /// \param min the minimum value + /// \param max the maximum value + /// \param rnType RandomNumberType to specify the type + /// \param equiv the equivalence class based on the parameter \p mod + /// \param mod the modulus used to reduce the equivalence class + /// \throw RandomNumberNotFound if the set is empty. + /// \details Ideally, the random integer created should be uniformly distributed + /// over {x | min \<= x \<= max and \p x is of rnType and x \% mod == equiv}. + /// However the actual distribution may not be uniform because sequential + /// search is used to find an appropriate number from a random starting + /// point. + /// \details May return (with very small probability) a pseudoprime when a prime + /// is requested and max \> lastSmallPrime*lastSmallPrime. \p lastSmallPrime + /// is declared in nbtheory.h. Integer(RandomNumberGenerator &rng, const Integer &min, const Integer &max, RandomNumberType rnType=ANY, const Integer &equiv=Zero(), const Integer &mod=One()); - //! \brief Exponentiates to a power of 2 - //! \returns the Integer 2e - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// \brief Exponentiates to a power of 2 + /// \returns the Integer 2e + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() static Integer CRYPTOPP_API Power2(size_t e); //@} - //! \name ENCODE/DECODE + /// \name ENCODE/DECODE //@{ - //! \brief Minimum number of bytes to encode this integer - //! \param sign enumeration indicating Signedness - //! \note The MinEncodedSize() of 0 is 1. + /// \brief Minimum number of bytes to encode this integer + /// \param sign enumeration indicating Signedness + /// \note The MinEncodedSize() of 0 is 1. size_t MinEncodedSize(Signedness sign=UNSIGNED) const; - //! \brief Encode in big-endian format - //! \param output big-endian byte array - //! \param outputLen length of the byte array - //! \param sign enumeration indicating Signedness - //! \details Unsigned means encode absolute value, signed means encode two's complement if negative. - //! \details outputLen can be used to ensure an Integer is encoded to an exact size (rather than a - //! minimum size). An exact size is useful, for example, when encoding to a field element size. + /// \brief Encode in big-endian format + /// \param output big-endian byte array + /// \param outputLen length of the byte array + /// \param sign enumeration indicating Signedness + /// \details Unsigned means encode absolute value, signed means encode two's complement if negative. + /// \details outputLen can be used to ensure an Integer is encoded to an exact size (rather than a + /// minimum size). An exact size is useful, for example, when encoding to a field element size. void Encode(byte *output, size_t outputLen, Signedness sign=UNSIGNED) const; - //! \brief Encode in big-endian format - //! \param bt BufferedTransformation object - //! \param outputLen length of the encoding - //! \param sign enumeration indicating Signedness - //! \details Unsigned means encode absolute value, signed means encode two's complement if negative. - //! \details outputLen can be used to ensure an Integer is encoded to an exact size (rather than a - //! minimum size). An exact size is useful, for example, when encoding to a field element size. + /// \brief Encode in big-endian format + /// \param bt BufferedTransformation object + /// \param outputLen length of the encoding + /// \param sign enumeration indicating Signedness + /// \details Unsigned means encode absolute value, signed means encode two's complement if negative. + /// \details outputLen can be used to ensure an Integer is encoded to an exact size (rather than a + /// minimum size). An exact size is useful, for example, when encoding to a field element size. void Encode(BufferedTransformation &bt, size_t outputLen, Signedness sign=UNSIGNED) const; - //! \brief Encode in DER format - //! \param bt BufferedTransformation object - //! \details Encodes the Integer using Distinguished Encoding Rules - //! The result is placed into a BufferedTransformation object + /// \brief Encode in DER format + /// \param bt BufferedTransformation object + /// \details Encodes the Integer using Distinguished Encoding Rules + /// The result is placed into a BufferedTransformation object void DEREncode(BufferedTransformation &bt) const; - //! \brief Encode absolute value as big-endian octet string - //! \param bt BufferedTransformation object - //! \param length the number of mytes to decode + /// \brief Encode absolute value as big-endian octet string + /// \param bt BufferedTransformation object + /// \param length the number of mytes to decode void DEREncodeAsOctetString(BufferedTransformation &bt, size_t length) const; - //! \brief Encode absolute value in OpenPGP format - //! \param output big-endian byte array - //! \param bufferSize length of the byte array - //! \returns length of the output - //! \details OpenPGPEncode places result into the buffer and returns the - //! number of bytes used for the encoding + /// \brief Encode absolute value in OpenPGP format + /// \param output big-endian byte array + /// \param bufferSize length of the byte array + /// \returns length of the output + /// \details OpenPGPEncode places result into the buffer and returns the + /// number of bytes used for the encoding size_t OpenPGPEncode(byte *output, size_t bufferSize) const; - //! \brief Encode absolute value in OpenPGP format - //! \param bt BufferedTransformation object - //! \returns length of the output - //! \details OpenPGPEncode places result into a BufferedTransformation object and returns the - //! number of bytes used for the encoding + /// \brief Encode absolute value in OpenPGP format + /// \param bt BufferedTransformation object + /// \returns length of the output + /// \details OpenPGPEncode places result into a BufferedTransformation object and returns the + /// number of bytes used for the encoding size_t OpenPGPEncode(BufferedTransformation &bt) const; - //! \brief Decode from big-endian byte array - //! \param input big-endian byte array - //! \param inputLen length of the byte array - //! \param sign enumeration indicating Signedness + /// \brief Decode from big-endian byte array + /// \param input big-endian byte array + /// \param inputLen length of the byte array + /// \param sign enumeration indicating Signedness void Decode(const byte *input, size_t inputLen, Signedness sign=UNSIGNED); - //! \brief Decode nonnegative value from big-endian byte array - //! \param bt BufferedTransformation object - //! \param inputLen length of the byte array - //! \param sign enumeration indicating Signedness - //! \note bt.MaxRetrievable() \>= inputLen. + /// \brief Decode nonnegative value from big-endian byte array + /// \param bt BufferedTransformation object + /// \param inputLen length of the byte array + /// \param sign enumeration indicating Signedness + /// \note bt.MaxRetrievable() \>= inputLen. void Decode(BufferedTransformation &bt, size_t inputLen, Signedness sign=UNSIGNED); - //! \brief Decode from BER format - //! \param input big-endian byte array - //! \param inputLen length of the byte array + /// \brief Decode from BER format + /// \param input big-endian byte array + /// \param inputLen length of the byte array void BERDecode(const byte *input, size_t inputLen); - //! \brief Decode from BER format - //! \param bt BufferedTransformation object + /// \brief Decode from BER format + /// \param bt BufferedTransformation object void BERDecode(BufferedTransformation &bt); - //! \brief Decode nonnegative value from big-endian octet string - //! \param bt BufferedTransformation object - //! \param length length of the byte array + /// \brief Decode nonnegative value from big-endian octet string + /// \param bt BufferedTransformation object + /// \param length length of the byte array void BERDecodeAsOctetString(BufferedTransformation &bt, size_t length); - //! \brief Exception thrown when an error is encountered decoding an OpenPGP integer + /// \brief Exception thrown when an error is encountered decoding an OpenPGP integer class OpenPGPDecodeErr : public Exception { public: OpenPGPDecodeErr() : Exception(INVALID_DATA_FORMAT, "OpenPGP decode error") {} }; - //! \brief Decode from OpenPGP format - //! \param input big-endian byte array - //! \param inputLen length of the byte array + /// \brief Decode from OpenPGP format + /// \param input big-endian byte array + /// \param inputLen length of the byte array void OpenPGPDecode(const byte *input, size_t inputLen); - //! \brief Decode from OpenPGP format - //! \param bt BufferedTransformation object + /// \brief Decode from OpenPGP format + /// \param bt BufferedTransformation object void OpenPGPDecode(BufferedTransformation &bt); //@} - //! \name ACCESSORS + /// \name ACCESSORS //@{ - //! \brief Determines if the Integer is convertable to Long - //! \returns true if *this can be represented as a signed long - //! \sa ConvertToLong() + /// \brief Determines if the Integer is convertable to Long + /// \returns true if *this can be represented as a signed long + /// \sa ConvertToLong() bool IsConvertableToLong() const; - //! \brief Convert the Integer to Long - //! \return equivalent signed long if possible, otherwise undefined - //! \sa IsConvertableToLong() + /// \brief Convert the Integer to Long + /// \return equivalent signed long if possible, otherwise undefined + /// \sa IsConvertableToLong() signed long ConvertToLong() const; - //! \brief Determines the number of bits required to represent the Integer - //! \returns number of significant bits = floor(log2(abs(*this))) + 1 + /// \brief Determines the number of bits required to represent the Integer + /// \returns number of significant bits = floor(log2(abs(*this))) + 1 unsigned int BitCount() const; - //! \brief Determines the number of bytes required to represent the Integer - //! \returns number of significant bytes = ceiling(BitCount()/8) + /// \brief Determines the number of bytes required to represent the Integer + /// \returns number of significant bytes = ceiling(BitCount()/8) unsigned int ByteCount() const; - //! \brief Determines the number of words required to represent the Integer - //! \returns number of significant words = ceiling(ByteCount()/sizeof(word)) + /// \brief Determines the number of words required to represent the Integer + /// \returns number of significant words = ceiling(ByteCount()/sizeof(word)) unsigned int WordCount() const; - //! \brief Provides the i-th bit of the Integer - //! \returns the i-th bit, i=0 being the least significant bit + /// \brief Provides the i-th bit of the Integer + /// \returns the i-th bit, i=0 being the least significant bit bool GetBit(size_t i) const; - //! \brief Provides the i-th byte of the Integer - //! \returns the i-th byte + /// \brief Provides the i-th byte of the Integer + /// \returns the i-th byte byte GetByte(size_t i) const; - //! \brief Provides the low order bits of the Integer - //! \returns n lowest bits of *this >> i + /// \brief Provides the low order bits of the Integer + /// \returns n lowest bits of *this >> i lword GetBits(size_t i, size_t n) const; - //! \brief Determines if the Integer is 0 - //! \returns true if the Integer is 0, false otherwise + /// \brief Determines if the Integer is 0 + /// \returns true if the Integer is 0, false otherwise bool IsZero() const {return !*this;} - //! \brief Determines if the Integer is non-0 - //! \returns true if the Integer is non-0, false otherwise + /// \brief Determines if the Integer is non-0 + /// \returns true if the Integer is non-0, false otherwise bool NotZero() const {return !IsZero();} - //! \brief Determines if the Integer is negative - //! \returns true if the Integer is negative, false otherwise + /// \brief Determines if the Integer is negative + /// \returns true if the Integer is negative, false otherwise bool IsNegative() const {return sign == NEGATIVE;} - //! \brief Determines if the Integer is non-negative - //! \returns true if the Integer is non-negative, false otherwise + /// \brief Determines if the Integer is non-negative + /// \returns true if the Integer is non-negative, false otherwise bool NotNegative() const {return !IsNegative();} - //! \brief Determines if the Integer is positive - //! \returns true if the Integer is positive, false otherwise + /// \brief Determines if the Integer is positive + /// \returns true if the Integer is positive, false otherwise bool IsPositive() const {return NotNegative() && NotZero();} - //! \brief Determines if the Integer is non-positive - //! \returns true if the Integer is non-positive, false otherwise + /// \brief Determines if the Integer is non-positive + /// \returns true if the Integer is non-positive, false otherwise bool NotPositive() const {return !IsPositive();} - //! \brief Determines if the Integer is even parity - //! \returns true if the Integer is even, false otherwise + /// \brief Determines if the Integer is even parity + /// \returns true if the Integer is even, false otherwise bool IsEven() const {return GetBit(0) == 0;} - //! \brief Determines if the Integer is odd parity - //! \returns true if the Integer is odd, false otherwise + /// \brief Determines if the Integer is odd parity + /// \returns true if the Integer is odd, false otherwise bool IsOdd() const {return GetBit(0) == 1;} //@} - //! \name MANIPULATORS + /// \name MANIPULATORS //@{ - //! \brief Assignment + /// \brief Assignment Integer& operator=(const Integer& t); - //! \brief Addition Assignment + /// \brief Addition Assignment Integer& operator+=(const Integer& t); - //! \brief Subtraction Assignment + /// \brief Subtraction Assignment Integer& operator-=(const Integer& t); - //! \brief Multiplication Assignment - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// \brief Multiplication Assignment + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() Integer& operator*=(const Integer& t) {return *this = Times(t);} - //! \brief Division Assignment + /// \brief Division Assignment Integer& operator/=(const Integer& t) {return *this = DividedBy(t);} - //! \brief Remainder Assignment - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// \brief Remainder Assignment + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() Integer& operator%=(const Integer& t) {return *this = Modulo(t);} - //! \brief Division Assignment + /// \brief Division Assignment Integer& operator/=(word t) {return *this = DividedBy(t);} - //! \brief Remainder Assignment - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// \brief Remainder Assignment + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() Integer& operator%=(word t) {return *this = Integer(POSITIVE, 0, Modulo(t));} - //! \brief Left-shift Assignment + /// \brief Left-shift Assignment Integer& operator<<=(size_t n); - //! \brief Right-shift Assignment + /// \brief Right-shift Assignment Integer& operator>>=(size_t n); - //! \brief Bitwise AND Assignment - //! \param t the other Integer - //! \returns the result of *this & t - //! \details operator&=() performs a bitwise AND on *this. Missing bits are truncated - //! at the most significant bit positions, so the result is as small as the - //! smaller of the operands. - //! \details Internally, Crypto++ uses a sign-magnitude representation. The library - //! does not attempt to interpret bits, and the result is always POSITIVE. If needed, - //! the integer should be converted to a 2's compliment representation before performing - //! the operation. - //! \since Crypto++ 6.0 + /// \brief Bitwise AND Assignment + /// \param t the other Integer + /// \returns the result of *this & t + /// \details operator&=() performs a bitwise AND on *this. Missing bits are truncated + /// at the most significant bit positions, so the result is as small as the + /// smaller of the operands. + /// \details Internally, Crypto++ uses a sign-magnitude representation. The library + /// does not attempt to interpret bits, and the result is always POSITIVE. If needed, + /// the integer should be converted to a 2's compliment representation before performing + /// the operation. + /// \since Crypto++ 6.0 Integer& operator&=(const Integer& t); - //! \brief Bitwise OR Assignment - //! \param t the second Integer - //! \returns the result of *this | t - //! \details operator|=() performs a bitwise OR on *this. Missing bits are shifted in - //! at the most significant bit positions, so the result is as large as the - //! larger of the operands. - //! \details Internally, Crypto++ uses a sign-magnitude representation. The library - //! does not attempt to interpret bits, and the result is always POSITIVE. If needed, - //! the integer should be converted to a 2's compliment representation before performing - //! the operation. - //! \since Crypto++ 6.0 + /// \brief Bitwise OR Assignment + /// \param t the second Integer + /// \returns the result of *this | t + /// \details operator|=() performs a bitwise OR on *this. Missing bits are shifted in + /// at the most significant bit positions, so the result is as large as the + /// larger of the operands. + /// \details Internally, Crypto++ uses a sign-magnitude representation. The library + /// does not attempt to interpret bits, and the result is always POSITIVE. If needed, + /// the integer should be converted to a 2's compliment representation before performing + /// the operation. + /// \since Crypto++ 6.0 Integer& operator|=(const Integer& t); - //! \brief Bitwise XOR Assignment - //! \param t the other Integer - //! \returns the result of *this ^ t - //! \details operator^=() performs a bitwise XOR on *this. Missing bits are shifted - //! in at the most significant bit positions, so the result is as large as the - //! larger of the operands. - //! \details Internally, Crypto++ uses a sign-magnitude representation. The library - //! does not attempt to interpret bits, and the result is always POSITIVE. If needed, - //! the integer should be converted to a 2's compliment representation before performing - //! the operation. - //! \since Crypto++ 6.0 + /// \brief Bitwise XOR Assignment + /// \param t the other Integer + /// \returns the result of *this ^ t + /// \details operator^=() performs a bitwise XOR on *this. Missing bits are shifted + /// in at the most significant bit positions, so the result is as large as the + /// larger of the operands. + /// \details Internally, Crypto++ uses a sign-magnitude representation. The library + /// does not attempt to interpret bits, and the result is always POSITIVE. If needed, + /// the integer should be converted to a 2's compliment representation before performing + /// the operation. + /// \since Crypto++ 6.0 Integer& operator^=(const Integer& t); - //! \brief Set this Integer to random integer - //! \param rng RandomNumberGenerator used to generate material - //! \param bitCount the number of bits in the resulting integer - //! \details The random integer created is uniformly distributed over [0, 2bitCount]. + /// \brief Set this Integer to random integer + /// \param rng RandomNumberGenerator used to generate material + /// \param bitCount the number of bits in the resulting integer + /// \details The random integer created is uniformly distributed over [0, 2bitCount]. void Randomize(RandomNumberGenerator &rng, size_t bitCount); - //! \brief Set this Integer to random integer - //! \param rng RandomNumberGenerator used to generate material - //! \param min the minimum value - //! \param max the maximum value - //! \details The random integer created is uniformly distributed over [min, max]. + /// \brief Set this Integer to random integer + /// \param rng RandomNumberGenerator used to generate material + /// \param min the minimum value + /// \param max the maximum value + /// \details The random integer created is uniformly distributed over [min, max]. void Randomize(RandomNumberGenerator &rng, const Integer &min, const Integer &max); - //! \brief Set this Integer to random integer of special form - //! \param rng RandomNumberGenerator used to generate material - //! \param min the minimum value - //! \param max the maximum value - //! \param rnType RandomNumberType to specify the type - //! \param equiv the equivalence class based on the parameter \p mod - //! \param mod the modulus used to reduce the equivalence class - //! \throw RandomNumberNotFound if the set is empty. - //! \details Ideally, the random integer created should be uniformly distributed - //! over {x | min \<= x \<= max and \p x is of rnType and x \% mod == equiv}. - //! However the actual distribution may not be uniform because sequential - //! search is used to find an appropriate number from a random starting - //! point. - //! \details May return (with very small probability) a pseudoprime when a prime - //! is requested and max \> lastSmallPrime*lastSmallPrime. \p lastSmallPrime - //! is declared in nbtheory.h. + /// \brief Set this Integer to random integer of special form + /// \param rng RandomNumberGenerator used to generate material + /// \param min the minimum value + /// \param max the maximum value + /// \param rnType RandomNumberType to specify the type + /// \param equiv the equivalence class based on the parameter \p mod + /// \param mod the modulus used to reduce the equivalence class + /// \throw RandomNumberNotFound if the set is empty. + /// \details Ideally, the random integer created should be uniformly distributed + /// over {x | min \<= x \<= max and \p x is of rnType and x \% mod == equiv}. + /// However the actual distribution may not be uniform because sequential + /// search is used to find an appropriate number from a random starting + /// point. + /// \details May return (with very small probability) a pseudoprime when a prime + /// is requested and max \> lastSmallPrime*lastSmallPrime. \p lastSmallPrime + /// is declared in nbtheory.h. bool Randomize(RandomNumberGenerator &rng, const Integer &min, const Integer &max, RandomNumberType rnType, const Integer &equiv=Zero(), const Integer &mod=One()); bool GenerateRandomNoThrow(RandomNumberGenerator &rng, const NameValuePairs ¶ms = g_nullNameValuePairs); @@ -454,179 +454,179 @@ public: throw RandomNumberNotFound(); } - //! \brief Set the n-th bit to value - //! \details 0-based numbering. + /// \brief Set the n-th bit to value + /// \details 0-based numbering. void SetBit(size_t n, bool value=1); - //! \brief Set the n-th byte to value - //! \details 0-based numbering. + /// \brief Set the n-th byte to value + /// \details 0-based numbering. void SetByte(size_t n, byte value); - //! \brief Reverse the Sign of the Integer + /// \brief Reverse the Sign of the Integer void Negate(); - //! \brief Sets the Integer to positive + /// \brief Sets the Integer to positive void SetPositive() {sign = POSITIVE;} - //! \brief Sets the Integer to negative + /// \brief Sets the Integer to negative void SetNegative() {if (!!(*this)) sign = NEGATIVE;} - //! \brief Swaps this Integer with another Integer + /// \brief Swaps this Integer with another Integer void swap(Integer &a); //@} - //! \name UNARY OPERATORS + /// \name UNARY OPERATORS //@{ - //! \brief Negation + /// \brief Negation bool operator!() const; - //! \brief Addition + /// \brief Addition Integer operator+() const {return *this;} - //! \brief Subtraction + /// \brief Subtraction Integer operator-() const; - //! \brief Pre-increment + /// \brief Pre-increment Integer& operator++(); - //! \brief Pre-decrement + /// \brief Pre-decrement Integer& operator--(); - //! \brief Post-increment + /// \brief Post-increment Integer operator++(int) {Integer temp = *this; ++*this; return temp;} - //! \brief Post-decrement + /// \brief Post-decrement Integer operator--(int) {Integer temp = *this; --*this; return temp;} //@} - //! \name BINARY OPERATORS + /// \name BINARY OPERATORS //@{ - //! \brief Perform signed comparison - //! \param a the Integer to comapre - //! \retval -1 if *this < a - //! \retval 0 if *this = a - //! \retval 1 if *this > a + /// \brief Perform signed comparison + /// \param a the Integer to comapre + /// \retval -1 if *this < a + /// \retval 0 if *this = a + /// \retval 1 if *this > a int Compare(const Integer& a) const; - //! \brief Addition + /// \brief Addition Integer Plus(const Integer &b) const; - //! \brief Subtraction + /// \brief Subtraction Integer Minus(const Integer &b) const; - //! \brief Multiplication - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// \brief Multiplication + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() Integer Times(const Integer &b) const; - //! \brief Division + /// \brief Division Integer DividedBy(const Integer &b) const; - //! \brief Remainder - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// \brief Remainder + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() Integer Modulo(const Integer &b) const; - //! \brief Division + /// \brief Division Integer DividedBy(word b) const; - //! \brief Remainder - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// \brief Remainder + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() word Modulo(word b) const; - //! \brief Bitwise AND - //! \param t the other Integer - //! \returns the result of *this & t - //! \details And() performs a bitwise AND on the operands. Missing bits are truncated - //! at the most significant bit positions, so the result is as small as the - //! smaller of the operands. - //! \details Internally, Crypto++ uses a sign-magnitude representation. The library - //! does not attempt to interpret bits, and the result is always POSITIVE. If needed, - //! the integer should be converted to a 2's compliment representation before performing - //! the operation. - //! \since Crypto++ 6.0 + /// \brief Bitwise AND + /// \param t the other Integer + /// \returns the result of *this & t + /// \details And() performs a bitwise AND on the operands. Missing bits are truncated + /// at the most significant bit positions, so the result is as small as the + /// smaller of the operands. + /// \details Internally, Crypto++ uses a sign-magnitude representation. The library + /// does not attempt to interpret bits, and the result is always POSITIVE. If needed, + /// the integer should be converted to a 2's compliment representation before performing + /// the operation. + /// \since Crypto++ 6.0 Integer And(const Integer& t) const; - //! \brief Bitwise OR - //! \param t the other Integer - //! \returns the result of *this | t - //! \details Or() performs a bitwise OR on the operands. Missing bits are shifted in - //! at the most significant bit positions, so the result is as large as the - //! larger of the operands. - //! \details Internally, Crypto++ uses a sign-magnitude representation. The library - //! does not attempt to interpret bits, and the result is always POSITIVE. If needed, - //! the integer should be converted to a 2's compliment representation before performing - //! the operation. - //! \since Crypto++ 6.0 + /// \brief Bitwise OR + /// \param t the other Integer + /// \returns the result of *this | t + /// \details Or() performs a bitwise OR on the operands. Missing bits are shifted in + /// at the most significant bit positions, so the result is as large as the + /// larger of the operands. + /// \details Internally, Crypto++ uses a sign-magnitude representation. The library + /// does not attempt to interpret bits, and the result is always POSITIVE. If needed, + /// the integer should be converted to a 2's compliment representation before performing + /// the operation. + /// \since Crypto++ 6.0 Integer Or(const Integer& t) const; - //! \brief Bitwise XOR - //! \param t the other Integer - //! \returns the result of *this ^ t - //! \details Xor() performs a bitwise XOR on the operands. Missing bits are shifted in - //! at the most significant bit positions, so the result is as large as the - //! larger of the operands. - //! \details Internally, Crypto++ uses a sign-magnitude representation. The library - //! does not attempt to interpret bits, and the result is always POSITIVE. If needed, - //! the integer should be converted to a 2's compliment representation before performing - //! the operation. - //! \since Crypto++ 6.0 + /// \brief Bitwise XOR + /// \param t the other Integer + /// \returns the result of *this ^ t + /// \details Xor() performs a bitwise XOR on the operands. Missing bits are shifted in + /// at the most significant bit positions, so the result is as large as the + /// larger of the operands. + /// \details Internally, Crypto++ uses a sign-magnitude representation. The library + /// does not attempt to interpret bits, and the result is always POSITIVE. If needed, + /// the integer should be converted to a 2's compliment representation before performing + /// the operation. + /// \since Crypto++ 6.0 Integer Xor(const Integer& t) const; - //! \brief Right-shift + /// \brief Right-shift Integer operator>>(size_t n) const {return Integer(*this)>>=n;} - //! \brief Left-shift + /// \brief Left-shift Integer operator<<(size_t n) const {return Integer(*this)<<=n;} //@} - //! \name OTHER ARITHMETIC FUNCTIONS + /// \name OTHER ARITHMETIC FUNCTIONS //@{ - //! \brief Retrieve the absolute value of this integer + /// \brief Retrieve the absolute value of this integer Integer AbsoluteValue() const; - //! \brief Add this integer to itself + /// \brief Add this integer to itself Integer Doubled() const {return Plus(*this);} - //! \brief Multiply this integer by itself - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// \brief Multiply this integer by itself + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() Integer Squared() const {return Times(*this);} - //! \brief Extract square root - //! \details if negative return 0, else return floor of square root + /// \brief Extract square root + /// \details if negative return 0, else return floor of square root Integer SquareRoot() const; - //! \brief Determine whether this integer is a perfect square + /// \brief Determine whether this integer is a perfect square bool IsSquare() const; - //! is 1 or -1 + /// is 1 or -1 bool IsUnit() const; - //! return inverse if 1 or -1, otherwise return 0 + /// return inverse if 1 or -1, otherwise return 0 Integer MultiplicativeInverse() const; - //! \brief calculate r and q such that (a == d*q + r) && (0 <= r < abs(d)) + /// \brief calculate r and q such that (a == d*q + r) && (0 <= r < abs(d)) static void CRYPTOPP_API Divide(Integer &r, Integer &q, const Integer &a, const Integer &d); - //! \brief use a faster division algorithm when divisor is short + /// \brief use a faster division algorithm when divisor is short static void CRYPTOPP_API Divide(word &r, Integer &q, const Integer &a, word d); - //! \brief returns same result as Divide(r, q, a, Power2(n)), but faster + /// \brief returns same result as Divide(r, q, a, Power2(n)), but faster static void CRYPTOPP_API DivideByPowerOf2(Integer &r, Integer &q, const Integer &a, unsigned int n); - //! greatest common divisor + /// greatest common divisor static Integer CRYPTOPP_API Gcd(const Integer &a, const Integer &n); - //! \brief calculate multiplicative inverse of *this mod n + /// \brief calculate multiplicative inverse of *this mod n Integer InverseMod(const Integer &n) const; - //! - //! \sa a_times_b_mod_c() and a_exp_b_mod_c() + /// + /// \sa a_times_b_mod_c() and a_exp_b_mod_c() word InverseMod(word n) const; //@} - //! \name INPUT/OUTPUT + /// \name INPUT/OUTPUT //@{ - //! \brief Extraction operator - //! \param in a reference to a std::istream - //! \param a a reference to an Integer - //! \returns a reference to a std::istream reference + /// \brief Extraction operator + /// \param in a reference to a std::istream + /// \param a a reference to an Integer + /// \returns a reference to a std::istream reference friend CRYPTOPP_DLL std::istream& CRYPTOPP_API operator>>(std::istream& in, Integer &a); - //! - //! \brief Insertion operator - //! \param out a reference to a std::ostream - //! \param a a constant reference to an Integer - //! \returns a reference to a std::ostream reference - //! \details The output integer responds to std::hex, std::oct, std::hex, std::upper and - //! std::lower. The output includes the suffix \a \b h (for hex), \a \b . (\a \b dot, for dec) - //! and \a \b o (for octal). There is currently no way to suppress the suffix. - //! \details If you want to print an Integer without the suffix or using an arbitrary base, then - //! use IntToString(). - //! \sa IntToString + /// + /// \brief Insertion operator + /// \param out a reference to a std::ostream + /// \param a a constant reference to an Integer + /// \returns a reference to a std::ostream reference + /// \details The output integer responds to std::hex, std::oct, std::hex, std::upper and + /// std::lower. The output includes the suffix \a \b h (for hex), \a \b . (\a \b dot, for dec) + /// and \a \b o (for octal). There is currently no way to suppress the suffix. + /// \details If you want to print an Integer without the suffix or using an arbitrary base, then + /// use IntToString(). + /// \sa IntToString friend CRYPTOPP_DLL std::ostream& CRYPTOPP_API operator<<(std::ostream& out, const Integer &a); //@} #ifndef CRYPTOPP_DOXYGEN_PROCESSING - //! modular multiplication + /// modular multiplication CRYPTOPP_DLL friend Integer CRYPTOPP_API a_times_b_mod_c(const Integer &x, const Integer& y, const Integer& m); - //! modular exponentiation + /// modular exponentiation CRYPTOPP_DLL friend Integer CRYPTOPP_API a_exp_b_mod_c(const Integer &x, const Integer& e, const Integer& m); #endif @@ -650,76 +650,76 @@ private: #endif }; -//! \brief Comparison +/// \brief Comparison inline bool operator==(const CryptoPP::Integer& a, const CryptoPP::Integer& b) {return a.Compare(b)==0;} -//! \brief Comparison +/// \brief Comparison inline bool operator!=(const CryptoPP::Integer& a, const CryptoPP::Integer& b) {return a.Compare(b)!=0;} -//! \brief Comparison +/// \brief Comparison inline bool operator> (const CryptoPP::Integer& a, const CryptoPP::Integer& b) {return a.Compare(b)> 0;} -//! \brief Comparison +/// \brief Comparison inline bool operator>=(const CryptoPP::Integer& a, const CryptoPP::Integer& b) {return a.Compare(b)>=0;} -//! \brief Comparison +/// \brief Comparison inline bool operator< (const CryptoPP::Integer& a, const CryptoPP::Integer& b) {return a.Compare(b)< 0;} -//! \brief Comparison +/// \brief Comparison inline bool operator<=(const CryptoPP::Integer& a, const CryptoPP::Integer& b) {return a.Compare(b)<=0;} -//! \brief Addition +/// \brief Addition inline CryptoPP::Integer operator+(const CryptoPP::Integer &a, const CryptoPP::Integer &b) {return a.Plus(b);} -//! \brief Subtraction +/// \brief Subtraction inline CryptoPP::Integer operator-(const CryptoPP::Integer &a, const CryptoPP::Integer &b) {return a.Minus(b);} -//! \brief Multiplication -//! \sa a_times_b_mod_c() and a_exp_b_mod_c() +/// \brief Multiplication +/// \sa a_times_b_mod_c() and a_exp_b_mod_c() inline CryptoPP::Integer operator*(const CryptoPP::Integer &a, const CryptoPP::Integer &b) {return a.Times(b);} -//! \brief Division +/// \brief Division inline CryptoPP::Integer operator/(const CryptoPP::Integer &a, const CryptoPP::Integer &b) {return a.DividedBy(b);} -//! \brief Remainder -//! \sa a_times_b_mod_c() and a_exp_b_mod_c() +/// \brief Remainder +/// \sa a_times_b_mod_c() and a_exp_b_mod_c() inline CryptoPP::Integer operator%(const CryptoPP::Integer &a, const CryptoPP::Integer &b) {return a.Modulo(b);} -//! \brief Division +/// \brief Division inline CryptoPP::Integer operator/(const CryptoPP::Integer &a, CryptoPP::word b) {return a.DividedBy(b);} -//! \brief Remainder -//! \sa a_times_b_mod_c() and a_exp_b_mod_c() +/// \brief Remainder +/// \sa a_times_b_mod_c() and a_exp_b_mod_c() inline CryptoPP::word operator%(const CryptoPP::Integer &a, CryptoPP::word b) {return a.Modulo(b);} -//! \brief Bitwise AND -//! \param a the first Integer -//! \param b the second Integer -//! \returns the result of a & b -//! \details operator&() performs a bitwise AND on the operands. Missing bits are truncated -//! at the most significant bit positions, so the result is as small as the -//! smaller of the operands. -//! \details Internally, Crypto++ uses a sign-magnitude representation. The library -//! does not attempt to interpret bits, and the result is always POSITIVE. If needed, -//! the integer should be converted to a 2's compliment representation before performing -//! the operation. -//! \since Crypto++ 6.0 +/// \brief Bitwise AND +/// \param a the first Integer +/// \param b the second Integer +/// \returns the result of a & b +/// \details operator&() performs a bitwise AND on the operands. Missing bits are truncated +/// at the most significant bit positions, so the result is as small as the +/// smaller of the operands. +/// \details Internally, Crypto++ uses a sign-magnitude representation. The library +/// does not attempt to interpret bits, and the result is always POSITIVE. If needed, +/// the integer should be converted to a 2's compliment representation before performing +/// the operation. +/// \since Crypto++ 6.0 inline CryptoPP::Integer operator&(const CryptoPP::Integer &a, const CryptoPP::Integer &b) {return a.And(b);} -//! \brief Bitwise OR -//! \param a the first Integer -//! \param b the second Integer -//! \returns the result of a | b -//! \details operator|() performs a bitwise OR on the operands. Missing bits are shifted in -//! at the most significant bit positions, so the result is as large as the -//! larger of the operands. -//! \details Internally, Crypto++ uses a sign-magnitude representation. The library -//! does not attempt to interpret bits, and the result is always POSITIVE. If needed, -//! the integer should be converted to a 2's compliment representation before performing -//! the operation. -//! \since Crypto++ 6.0 +/// \brief Bitwise OR +/// \param a the first Integer +/// \param b the second Integer +/// \returns the result of a | b +/// \details operator|() performs a bitwise OR on the operands. Missing bits are shifted in +/// at the most significant bit positions, so the result is as large as the +/// larger of the operands. +/// \details Internally, Crypto++ uses a sign-magnitude representation. The library +/// does not attempt to interpret bits, and the result is always POSITIVE. If needed, +/// the integer should be converted to a 2's compliment representation before performing +/// the operation. +/// \since Crypto++ 6.0 inline CryptoPP::Integer operator|(const CryptoPP::Integer &a, const CryptoPP::Integer &b) {return a.Or(b);} -//! \brief Bitwise XOR -//! \param a the first Integer -//! \param b the second Integer -//! \returns the result of a ^ b -//! \details operator^() performs a bitwise XOR on the operands. Missing bits are shifted -//! in at the most significant bit positions, so the result is as large as the -//! larger of the operands. -//! \details Internally, Crypto++ uses a sign-magnitude representation. The library -//! does not attempt to interpret bits, and the result is always POSITIVE. If needed, -//! the integer should be converted to a 2's compliment representation before performing -//! the operation. -//! \since Crypto++ 6.0 +/// \brief Bitwise XOR +/// \param a the first Integer +/// \param b the second Integer +/// \returns the result of a ^ b +/// \details operator^() performs a bitwise XOR on the operands. Missing bits are shifted +/// in at the most significant bit positions, so the result is as large as the +/// larger of the operands. +/// \details Internally, Crypto++ uses a sign-magnitude representation. The library +/// does not attempt to interpret bits, and the result is always POSITIVE. If needed, +/// the integer should be converted to a 2's compliment representation before performing +/// the operation. +/// \since Crypto++ 6.0 inline CryptoPP::Integer operator^(const CryptoPP::Integer &a, const CryptoPP::Integer &b) {return a.Xor(b);} NAMESPACE_END diff --git a/iterhash.h b/iterhash.h index d51e155b..646c49be 100644 --- a/iterhash.h +++ b/iterhash.h @@ -18,8 +18,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class HashInputTooLong -//! \brief Exception thrown when trying to hash more data than is allowed by a hash function +/// \class HashInputTooLong +/// \brief Exception thrown when trying to hash more data than is allowed by a hash function class CRYPTOPP_DLL HashInputTooLong : public InvalidDataFormat { public: @@ -27,57 +27,57 @@ public: : InvalidDataFormat("IteratedHashBase: input data exceeds maximum allowed by hash function " + alg) {} }; -//! \class IteratedHashBase -//! \brief Iterated hash base class -//! \tparam T Hash word type -//! \tparam BASE HashTransformation derived class -//! \details IteratedHashBase provides an interface for block-based iterated hashes -//! \sa HashTransformation, MessageAuthenticationCode +/// \class IteratedHashBase +/// \brief Iterated hash base class +/// \tparam T Hash word type +/// \tparam BASE HashTransformation derived class +/// \details IteratedHashBase provides an interface for block-based iterated hashes +/// \sa HashTransformation, MessageAuthenticationCode template class CRYPTOPP_NO_VTABLE IteratedHashBase : public BASE { public: typedef T HashWordType; - //! \brief Construct an IteratedHashBase + /// \brief Construct an IteratedHashBase IteratedHashBase() : m_countLo(0), m_countHi(0) {} - //! \brief Provides the input block size most efficient for this cipher. - //! \return The input block size that is most efficient for the cipher - //! \details The base class implementation returns MandatoryBlockSize(). - //! \note Optimal input length is - //! n * OptimalBlockSize() - GetOptimalBlockSizeUsed() for any n \> 0. + /// \brief Provides the input block size most efficient for this cipher. + /// \return The input block size that is most efficient for the cipher + /// \details The base class implementation returns MandatoryBlockSize(). + /// \note Optimal input length is + /// n * OptimalBlockSize() - GetOptimalBlockSizeUsed() for any n \> 0. unsigned int OptimalBlockSize() const {return this->BlockSize();} - //! \brief Provides input and output data alignment for optimal performance. - //! \return the input data alignment that provides optimal performance - //! \details OptimalDataAlignment returns the natural alignment of the hash word. + /// \brief Provides input and output data alignment for optimal performance. + /// \return the input data alignment that provides optimal performance + /// \details OptimalDataAlignment returns the natural alignment of the hash word. unsigned int OptimalDataAlignment() const {return GetAlignmentOf();} - //! \brief Updates a hash with additional input - //! \param input the additional input as a buffer - //! \param length the size of the buffer, in bytes + /// \brief Updates a hash with additional input + /// \param input the additional input as a buffer + /// \param length the size of the buffer, in bytes void Update(const byte *input, size_t length); - //! \brief Requests space which can be written into by the caller - //! \param size the requested size of the buffer - //! \details The purpose of this method is to help avoid extra memory allocations. - //! \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, - //! size is the requested size of the buffer. When the call returns, size is the size of - //! the array returned to the caller. - //! \details The base class implementation sets size to 0 and returns NULL. - //! \note Some objects, like ArraySink, cannot create a space because its fixed. + /// \brief Requests space which can be written into by the caller + /// \param size the requested size of the buffer + /// \details The purpose of this method is to help avoid extra memory allocations. + /// \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, + /// size is the requested size of the buffer. When the call returns, size is the size of + /// the array returned to the caller. + /// \details The base class implementation sets size to 0 and returns NULL. + /// \note Some objects, like ArraySink, cannot create a space because its fixed. byte * CreateUpdateSpace(size_t &size); - //! \brief Restart the hash - //! \details Discards the current state, and restart for a new message + /// \brief Restart the hash + /// \details Discards the current state, and restart for a new message void Restart(); - //! \brief Computes the hash of the current message - //! \param digest a pointer to the buffer to receive the hash - //! \param digestSize the size of the truncated digest, in bytes - //! \details TruncatedFinal() call Final() and then copies digestSize bytes to digest. - //! The hash is restarted the hash for the next message. + /// \brief Computes the hash of the current message + /// \param digest a pointer to the buffer to receive the hash + /// \param digestSize the size of the truncated digest, in bytes + /// \details TruncatedFinal() call Final() and then copies digestSize bytes to digest. + /// The hash is restarted the hash for the next message. void TruncatedFinal(byte *digest, size_t digestSize); protected: @@ -99,14 +99,14 @@ private: T m_countLo, m_countHi; }; -//! \class IteratedHash -//! \brief Iterated hash base class -//! \tparam T_HashWordType Hash word type -//! \tparam T_Endianness Endianness type of hash -//! \tparam T_BlockSize Block size of the hash -//! \tparam T_Base HashTransformation derived class -//! \details IteratedHash provides a default implementation for block-based iterated hashes -//! \sa HashTransformation, MessageAuthenticationCode +/// \class IteratedHash +/// \brief Iterated hash base class +/// \tparam T_HashWordType Hash word type +/// \tparam T_Endianness Endianness type of hash +/// \tparam T_BlockSize Block size of the hash +/// \tparam T_Base HashTransformation derived class +/// \details IteratedHash provides a default implementation for block-based iterated hashes +/// \sa HashTransformation, MessageAuthenticationCode template class CRYPTOPP_NO_VTABLE IteratedHash : public IteratedHashBase { @@ -120,22 +120,22 @@ public: virtual ~IteratedHash() {} - //! \brief Provides the block size of the hash - //! \return the block size of the hash, in bytes - //! \details BlockSize() returns T_BlockSize. + /// \brief Provides the block size of the hash + /// \return the block size of the hash, in bytes + /// \details BlockSize() returns T_BlockSize. unsigned int BlockSize() const {return T_BlockSize;} - //! \brief Provides the byte order of the hash - //! \returns the byte order of the hash as an enumeration - //! \details GetByteOrder() returns T_Endianness::ToEnum(). - //! \sa ByteOrder() + /// \brief Provides the byte order of the hash + /// \returns the byte order of the hash as an enumeration + /// \details GetByteOrder() returns T_Endianness::ToEnum(). + /// \sa ByteOrder() ByteOrder GetByteOrder() const {return T_Endianness::ToEnum();} - //! \brief Adjusts the byte ordering of the hash - //! \param out the output buffer - //! \param in the input buffer - //! \param byteCount the size of the buffers, in bytes - //! \details CorrectEndianess() calls ConditionalByteReverse() using T_Endianness. + /// \brief Adjusts the byte ordering of the hash + /// \param out the output buffer + /// \param in the input buffer + /// \param byteCount the size of the buffers, in bytes + /// \details CorrectEndianess() calls ConditionalByteReverse() using T_Endianness. inline void CorrectEndianess(HashWordType *out, const HashWordType *in, size_t byteCount) { ConditionalByteReverse(T_Endianness::ToEnum(), out, in, byteCount); @@ -146,16 +146,16 @@ protected: FixedSizeSecBlock m_data; }; -//! \class IteratedHashWithStaticTransform -//! \brief Iterated hash with a static transformation function -//! \tparam T_HashWordType Hash word type -//! \tparam T_Endianness Endianness type of hash -//! \tparam T_BlockSize Block size of the hash -//! \tparam T_StateSize Internal state size of the hash -//! \tparam T_Transform HashTransformation derived class -//! \tparam T_DigestSize Digest size of the hash -//! \tparam T_StateAligned Flag indicating if state is 16-byte aligned -//! \sa HashTransformation, MessageAuthenticationCode +/// \class IteratedHashWithStaticTransform +/// \brief Iterated hash with a static transformation function +/// \tparam T_HashWordType Hash word type +/// \tparam T_Endianness Endianness type of hash +/// \tparam T_BlockSize Block size of the hash +/// \tparam T_StateSize Internal state size of the hash +/// \tparam T_Transform HashTransformation derived class +/// \tparam T_DigestSize Digest size of the hash +/// \tparam T_StateAligned Flag indicating if state is 16-byte aligned +/// \sa HashTransformation, MessageAuthenticationCode template class CRYPTOPP_NO_VTABLE IteratedHashWithStaticTransform : public ClonableImpl, T_Transform> > @@ -165,9 +165,9 @@ public: virtual ~IteratedHashWithStaticTransform() {} - //! \brief Provides the digest size of the hash - //! \return the digest size of the hash, in bytes - //! \details DigestSize() returns DIGESTSIZE. + /// \brief Provides the digest size of the hash + /// \return the digest size of the hash, in bytes + /// \details DigestSize() returns DIGESTSIZE. unsigned int DigestSize() const {return DIGESTSIZE;}; protected: diff --git a/kalyna.h b/kalyna.h index 36fc6d08..28fe0cfb 100644 --- a/kalyna.h +++ b/kalyna.h @@ -1,15 +1,15 @@ // kalyna.h - written and placed in the public domain by Jeffrey Walton // Based on public domain code by Keru Kuro. -//! \file kalyna.h -//! \brief Classes for the Kalyna block cipher -//! \details The Crypto++ implementation relied upon three sources. First was Oliynykov, Gorbenko, Kazymyrov, -//! Ruzhentsev, Kuznetsov, Gorbenko, Dyrda, Dolgov, Pushkaryov, Mordvinov and Kaidalov's "A New Encryption -//! Standard of Ukraine: The Kalyna Block Cipher" (http://eprint.iacr.org/2015/650.pdf). Second was Roman -//! Oliynykov and Oleksandr Kazymyrov's GitHub with the reference implementation -//! (http://github.com/Roman-Oliynykov/Kalyna-reference). The third resource was Keru Kuro's implementation -//! of Kalyna in CppCrypto (http://sourceforge.net/projects/cppcrypto/). Kuro has an outstanding -//! implementation that performed better than the reference implementation and our initial attempts. +/// \file kalyna.h +/// \brief Classes for the Kalyna block cipher +/// \details The Crypto++ implementation relied upon three sources. First was Oliynykov, Gorbenko, Kazymyrov, +/// Ruzhentsev, Kuznetsov, Gorbenko, Dyrda, Dolgov, Pushkaryov, Mordvinov and Kaidalov's "A New Encryption +/// Standard of Ukraine: The Kalyna Block Cipher" (http://eprint.iacr.org/2015/650.pdf). Second was Roman +/// Oliynykov and Oleksandr Kazymyrov's GitHub with the reference implementation +/// (http://github.com/Roman-Oliynykov/Kalyna-reference). The third resource was Keru Kuro's implementation +/// of Kalyna in CppCrypto (http://sourceforge.net/projects/cppcrypto/). Kuro has an outstanding +/// implementation that performed better than the reference implementation and our initial attempts. #ifndef CRYPTOPP_KALYNA_H #define CRYPTOPP_KALYNA_H @@ -20,63 +20,63 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Kalyna_Info -//! \brief Kalyna block cipher information -//! \details Kalyna key sizes and block sizes do not fit well into the library. Rather -//! than using VariableKeyLength (which is wrong) or using a GeometricKeyLength -//! (a new class), we just unroll it here. Note that the step size, Q, is still -//! wrong for this implementation. -//! \since Crypto++ 6.0 +/// \class Kalyna_Info +/// \brief Kalyna block cipher information +/// \details Kalyna key sizes and block sizes do not fit well into the library. Rather +/// than using VariableKeyLength (which is wrong) or using a GeometricKeyLength +/// (a new class), we just unroll it here. Note that the step size, Q, is still +/// wrong for this implementation. +/// \since Crypto++ 6.0 struct Kalyna_Info : public VariableBlockSize<16, 16, 64> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "Kalyna";} - //! \brief The minimum key length used by the algorithm provided as a constant - //! \details MIN_KEYLENGTH is provided in bytes, not bits + /// \brief The minimum key length used by the algorithm provided as a constant + /// \details MIN_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(MIN_KEYLENGTH=16) - //! \brief The maximum key length used by the algorithm provided as a constant - //! \details MIN_KEYLENGTH is provided in bytes, not bits + /// \brief The maximum key length used by the algorithm provided as a constant + /// \details MIN_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(MAX_KEYLENGTH=64) - //! \brief The default key length used by the algorithm provided as a constant - //! \details MIN_KEYLENGTH is provided in bytes, not bits + /// \brief The default key length used by the algorithm provided as a constant + /// \details MIN_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=16) - //! \brief The default IV requirements for the algorithm provided as a constant - //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement - //! in cryptlib.h for allowed values. + /// \brief The default IV requirements for the algorithm provided as a constant + /// \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement + /// in cryptlib.h for allowed values. CRYPTOPP_CONSTANT(IV_REQUIREMENT=SimpleKeyingInterface::UNIQUE_IV) - //! \brief The default initialization vector length for the algorithm provided as a constant - //! \details IV_LENGTH is provided in bytes, not bits. Kalyna has two different block sizes for - //! each key length. This function returns the default block size for the defult key length. + /// \brief The default initialization vector length for the algorithm provided as a constant + /// \details IV_LENGTH is provided in bytes, not bits. Kalyna has two different block sizes for + /// each key length. This function returns the default block size for the defult key length. CRYPTOPP_CONSTANT(IV_LENGTH=16) - //! \brief Provides a valid key length for the algorithm provided by a static function. - //! \param keylength the size of the key, in bytes - //! \details The key length depends on the block size. For each block size, 128, 256 and 512, - //! the key length can be either the block size or twice the block size. That means the - //! valid key lengths are 126, 256, 512 and 1024. Additionally, it means a key length of, - //! say, 32 could be used with either 128-block size or 256-block size. + /// \brief Provides a valid key length for the algorithm provided by a static function. + /// \param keylength the size of the key, in bytes + /// \details The key length depends on the block size. For each block size, 128, 256 and 512, + /// the key length can be either the block size or twice the block size. That means the + /// valid key lengths are 126, 256, 512 and 1024. Additionally, it means a key length of, + /// say, 32 could be used with either 128-block size or 256-block size. CRYPTOPP_STATIC_CONSTEXPR size_t CRYPTOPP_API StaticGetValidKeyLength(size_t keylength) { return (keylength >= 64) ? 64 : (keylength >= 32) ? 32 : 16; } - //! \brief Validates the blocksize for Kalyna. - //! \param blocksize the candidate blocksize - //! \param alg an Algorithm object used if the blocksize is invalid - //! \throws InvalidBlockSize if the blocksize is invalid - //! \details ThrowIfInvalidBlockSize() validates the blocksize and throws if invalid. + /// \brief Validates the blocksize for Kalyna. + /// \param blocksize the candidate blocksize + /// \param alg an Algorithm object used if the blocksize is invalid + /// \throws InvalidBlockSize if the blocksize is invalid + /// \details ThrowIfInvalidBlockSize() validates the blocksize and throws if invalid. inline void ThrowIfInvalidBlockSize(int blocksize, const Algorithm *alg) { if ( blocksize != 16 && blocksize != 32 && blocksize != 64) throw InvalidBlockSize(alg ? alg->AlgorithmName() : std::string("VariableBlockSize"), blocksize); } - //! \brief Validates the blocksize for Kalyna. - //! \param keylength the key length of the cipher - //! \param blocksize the candidate blocksize - //! \param alg an Algorithm object used if the blocksize is invalid - //! \throws InvalidBlockSize if the blocksize is invalid - //! \details ThrowIfInvalidBlockSize() validates the blocksize under a key and throws if invalid. + /// \brief Validates the blocksize for Kalyna. + /// \param keylength the key length of the cipher + /// \param blocksize the candidate blocksize + /// \param alg an Algorithm object used if the blocksize is invalid + /// \throws InvalidBlockSize if the blocksize is invalid + /// \details ThrowIfInvalidBlockSize() validates the blocksize under a key and throws if invalid. inline void ThrowIfInvalidBlockSize(int keylength, int blocksize, const Algorithm *alg) { if ( ((keylength == 16) && (blocksize != 16)) || @@ -88,26 +88,26 @@ struct Kalyna_Info : public VariableBlockSize<16, 16, 64> } }; -//! \class Kalyna -//! \brief Kalyna block cipher -//! \since Crypto++ 6.0 +/// \class Kalyna +/// \brief Kalyna block cipher +/// \since Crypto++ 6.0 class Kalyna : public Kalyna_Info, public BlockCipherDocumentation { public: class CRYPTOPP_NO_VTABLE Base : public VariableBlockCipherImpl { public: - //! \brief Provides the name of this algorithm - //! \return the standard algorithm name - //! \details If the object is unkeyed, then the generic name "Kalyna" is returned - //! to the caller. If the algorithm is keyed, then a two or three part name is - //! returned to the caller. The name follows DSTU 7624:2014, where block size is - //! provided first and then key length. The library uses a dash to identify block size - //! and parenthesis to identify key length. For example, Kalyna-128(256) is Kalyna - //! with a 128-bit block size and a 256-bit key length. If a mode is associated - //! with the object, then it follows as expected. For example, Kalyna-128(256)/ECB. - //! DSTU is a little more complex with more parameters, dashes, underscores, but the - //! library does not use the delimiters or full convention. + /// \brief Provides the name of this algorithm + /// \return the standard algorithm name + /// \details If the object is unkeyed, then the generic name "Kalyna" is returned + /// to the caller. If the algorithm is keyed, then a two or three part name is + /// returned to the caller. The name follows DSTU 7624:2014, where block size is + /// provided first and then key length. The library uses a dash to identify block size + /// and parenthesis to identify key length. For example, Kalyna-128(256) is Kalyna + /// with a 128-bit block size and a 256-bit key length. If a mode is associated + /// with the object, then it follows as expected. For example, Kalyna-128(256)/ECB. + /// DSTU is a little more complex with more parameters, dashes, underscores, but the + /// library does not use the delimiters or full convention. std::string AlgorithmName() const { return m_blocksize ? "Kalyna-" + IntToString(m_blocksize*8) + "(" + IntToString(m_kl*8) + ")" : StaticAlgorithmName(); } diff --git a/keccak.h b/keccak.h index e8c1153b..9b111c76 100644 --- a/keccak.h +++ b/keccak.h @@ -1,13 +1,13 @@ // keccak.h - originally written and placed in the public domain by Wei Dai -//! \file keccak.h -//! \brief Classes for Keccak message digests -//! \details The Crypto++ Keccak implementation uses F1600 with XOF d=0x01. -//! FIPS 202 conformance (XOF d=0x06) is available in SHA3 classes. -//! \details Keccak will likely change in the future to accommodate extensibility of the -//! round function and the XOF functions. -//! \sa Keccak -//! \since Crypto++ 5.6.4 +/// \file keccak.h +/// \brief Classes for Keccak message digests +/// \details The Crypto++ Keccak implementation uses F1600 with XOF d=0x01. +/// FIPS 202 conformance (XOF d=0x06) is available in SHA3 classes. +/// \details Keccak will likely change in the future to accommodate extensibility of the +/// round function and the XOF functions. +/// \sa Keccak +/// \since Crypto++ 5.6.4 #ifndef CRYPTOPP_KECCAK_H #define CRYPTOPP_KECCAK_H @@ -17,36 +17,36 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Keccak -//! \brief Keccak message digest base class -//! \details The Crypto++ Keccak implementation uses F1600 with XOF d=0x01. -//! FIPS 202 conformance (XOF d=0x06) is available in SHA3 classes. -//! \details Keccak is the base class for Keccak_224, Keccak_256, Keccak_384 and Keccak_512. -//! Library users should instantiate a derived class, and only use Keccak -//! as a base class reference or pointer. -//! \details Keccak will likely change in the future to accommodate extensibility of the -//! round function and the XOF functions. -//! \details Perform the following to specify a different digest size. The class will use F1600, -//! XOF d=0x01, and a new vaue for r() (which will be 200-2*24 = 152). -//! 
  Keccack_192 : public Keccack
-//!   {
-//!     public:
-//!       CRYPTOPP_CONSTANT(DIGESTSIZE = 24)
-//!       Keccack_192() : Keccack(DIGESTSIZE) {}
-//!   };
-//!
-//! -//! \sa SHA3, Keccak_224, Keccak_256, Keccak_384 and Keccak_512. -//! \since Crypto++ 5.6.4 +/// \class Keccak +/// \brief Keccak message digest base class +/// \details The Crypto++ Keccak implementation uses F1600 with XOF d=0x01. +/// FIPS 202 conformance (XOF d=0x06) is available in SHA3 classes. +/// \details Keccak is the base class for Keccak_224, Keccak_256, Keccak_384 and Keccak_512. +/// Library users should instantiate a derived class, and only use Keccak +/// as a base class reference or pointer. +/// \details Keccak will likely change in the future to accommodate extensibility of the +/// round function and the XOF functions. +/// \details Perform the following to specify a different digest size. The class will use F1600, +/// XOF d=0x01, and a new vaue for r() (which will be 200-2*24 = 152). +/// 
  Keccack_192 : public Keccack
+///   {
+///     public:
+///       CRYPTOPP_CONSTANT(DIGESTSIZE = 24)
+///       Keccack_192() : Keccack(DIGESTSIZE) {}
+///   };
+///
+/// +/// \sa SHA3, Keccak_224, Keccak_256, Keccak_384 and Keccak_512. +/// \since Crypto++ 5.6.4 class Keccak : public HashTransformation { public: - //! \brief Construct a Keccak - //! \param digestSize the digest size, in bytes - //! \details Keccak is the base class for Keccak_224, Keccak_256, Keccak_384 and Keccak_512. - //! Library users should instantiate a derived class, and only use Keccak - //! as a base class reference or pointer. - //! \since Crypto++ 5.6.4 + /// \brief Construct a Keccak + /// \param digestSize the digest size, in bytes + /// \details Keccak is the base class for Keccak_224, Keccak_256, Keccak_384 and Keccak_512. + /// Library users should instantiate a derived class, and only use Keccak + /// as a base class reference or pointer. + /// \since Crypto++ 5.6.4 Keccak(unsigned int digestSize) : m_digestSize(digestSize) {Restart();} unsigned int DigestSize() const {return m_digestSize;} std::string AlgorithmName() const {return "Keccak-" + IntToString(m_digestSize*8);} @@ -66,10 +66,10 @@ protected: unsigned int m_digestSize, m_counter; }; -//! \class Keccak_224 -//! \tparam T_DigestSize controls the digest size as a template parameter instead of a per-class constant -//! \brief Keccak-X message digest, template for more fine-grained typedefs -//! \since Crypto++ 6.0.0 +/// \class Keccak_224 +/// \tparam T_DigestSize controls the digest size as a template parameter instead of a per-class constant +/// \brief Keccak-X message digest, template for more fine-grained typedefs +/// \since Crypto++ 6.0.0 template class Keccak_Final : public Keccak { @@ -77,7 +77,7 @@ public: CRYPTOPP_CONSTANT(DIGESTSIZE = T_DigestSize) CRYPTOPP_CONSTANT(BLOCKSIZE = 200 - 2 * DIGESTSIZE) - //! \brief Construct a Keccak-X message digest + /// \brief Construct a Keccak-X message digest Keccak_Final() : Keccak(DIGESTSIZE) {} static std::string StaticAlgorithmName() { return "Keccak-" + IntToString(DIGESTSIZE * 8); } unsigned int BlockSize() const { return BLOCKSIZE; } @@ -86,20 +86,20 @@ private: CRYPTOPP_COMPILE_ASSERT(BLOCKSIZE > (int)T_DigestSize); // this is a general expectation by HMAC }; -//! \brief Keccak-224 message digest -//! \since Crypto++ 5.6.4 +/// \brief Keccak-224 message digest +/// \since Crypto++ 5.6.4 typedef Keccak_Final<28> Keccak_224; -//! \brief Keccak-256 message digest -//! \since Crypto++ 5.6.4 +/// \brief Keccak-256 message digest +/// \since Crypto++ 5.6.4 typedef Keccak_Final<32> Keccak_256; -//! \brief Keccak-384 message digest -//! \since Crypto++ 5.6.4 +/// \brief Keccak-384 message digest +/// \since Crypto++ 5.6.4 typedef Keccak_Final<48> Keccak_384; -//! \brief Keccak-512 message digest -//! \since Crypto++ 5.6.4 +/// \brief Keccak-512 message digest +/// \since Crypto++ 5.6.4 typedef Keccak_Final<64> Keccak_512; NAMESPACE_END diff --git a/lubyrack.h b/lubyrack.h index 25a75e84..4aadab2c 100644 --- a/lubyrack.h +++ b/lubyrack.h @@ -1,7 +1,7 @@ // lubyrack.h - originally written and placed in the public domain by Wei Dai -//! \file lubyrack.h -//! \brief Classes for the Luby-Rackoff block cipher +/// \file lubyrack.h +/// \brief Classes for the Luby-Rackoff block cipher #ifndef CRYPTOPP_LUBYRACK_H #define CRYPTOPP_LUBYRACK_H @@ -11,16 +11,16 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class LR_Info -//! \brief Luby-Rackoff block cipher information +/// \class LR_Info +/// \brief Luby-Rackoff block cipher information template struct LR_Info : public VariableKeyLength<16, 0, 2*(INT_MAX/2), 2>, public FixedBlockSize<2*T::DIGESTSIZE> { static std::string StaticAlgorithmName() {return std::string("LR/")+T::StaticAlgorithmName();} }; -//! \class LR -//! \brief Luby-Rackoff block cipher +/// \class LR +/// \brief Luby-Rackoff block cipher template class LR : public LR_Info, public BlockCipherDocumentation { diff --git a/luc.h b/luc.h index adea781f..45f322b8 100644 --- a/luc.h +++ b/luc.h @@ -1,10 +1,10 @@ // luc.h - originally written and placed in the public domain by Wei Dai -//! \file luc.h -//! \brief Classes for the LUC cryptosystem -//! \details This class is here for historical and pedagogical interest. It has no practical advantages over other -//! trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes -//! defined later in this .h file may be of more practical interest. +/// \file luc.h +/// \brief Classes for the LUC cryptosystem +/// \details This class is here for historical and pedagogical interest. It has no practical advantages over other +/// trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes +/// defined later in this .h file may be of more practical interest. #ifndef CRYPTOPP_LUC_H #define CRYPTOPP_LUC_H @@ -29,10 +29,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief The LUC function. -//! \details This class is here for historical and pedagogical interest. It has no practical advantages over other -//! trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes -//! defined later in this .h file may be of more practical interest. +/// \brief The LUC function. +/// \details This class is here for historical and pedagogical interest. It has no practical advantages over other +/// trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes +/// defined later in this .h file may be of more practical interest. class LUCFunction : public TrapdoorFunction, public PublicKey { typedef LUCFunction ThisClass; @@ -40,9 +40,9 @@ class LUCFunction : public TrapdoorFunction, public PublicKey public: virtual ~LUCFunction() {} - //! \brief Initialize a LUC public key with {n,e} - //! \param n the modulus - //! \param e the public exponent + /// \brief Initialize a LUC public key with {n,e} + /// \param n the modulus + /// \param e the public exponent void Initialize(const Integer &n, const Integer &e) {m_n = n; m_e = e;} @@ -68,10 +68,10 @@ protected: Integer m_n, m_e; }; -//! \brief The LUC inverse function. -//! \details This class is here for historical and pedagogical interest. It has no practical advantages over other -//! trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes -//! defined later in this .h file may be of more practical interest. +/// \brief The LUC inverse function. +/// \details This class is here for historical and pedagogical interest. It has no practical advantages over other +/// trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes +/// defined later in this .h file may be of more practical interest. class InvertibleLUCFunction : public LUCFunction, public TrapdoorFunctionInverse, public PrivateKey { typedef InvertibleLUCFunction ThisClass; @@ -79,23 +79,23 @@ class InvertibleLUCFunction : public LUCFunction, public TrapdoorFunctionInverse public: virtual ~InvertibleLUCFunction() {} - //! \brief Create a LUC private key - //! \param rng a RandomNumberGenerator derived class - //! \param modulusBits the size of the modulus, in bits - //! \param eStart the desired starting public exponent - //! \details Initialize() creates a new keypair using a starting public exponent of 17. - //! \details This function overload of Initialize() creates a new keypair because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a LUC private key + /// \param rng a RandomNumberGenerator derived class + /// \param modulusBits the size of the modulus, in bits + /// \param eStart the desired starting public exponent + /// \details Initialize() creates a new keypair using a starting public exponent of 17. + /// \details This function overload of Initialize() creates a new keypair because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits, const Integer &eStart=17); - //! \brief Initialize a LUC private key with {n,e,p,q,dp,dq,u} - //! \param n modulus - //! \param e public exponent - //! \param p first prime factor - //! \param q second prime factor - //! \param u q-1 mod p - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize a LUC private key with {n,e,p,q,dp,dq,u} + /// \param n modulus + /// \param e public exponent + /// \param p first prime factor + /// \param q second prime factor + /// \param u q-1 mod p + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const Integer &n, const Integer &e, const Integer &p, const Integer &q, const Integer &u) {m_n = n; m_e = e; m_p = p; m_q = q; m_u = u;} @@ -130,22 +130,22 @@ struct LUC typedef InvertibleLUCFunction PrivateKey; }; -//! \brief LUC cryptosystem -//! \tparam STANDARD signature standard -//! \details This class is here for historical and pedagogical interest. It has no practical advantages over other -//! trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes -//! defined later in this .h file may be of more practical interest. +/// \brief LUC cryptosystem +/// \tparam STANDARD signature standard +/// \details This class is here for historical and pedagogical interest. It has no practical advantages over other +/// trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes +/// defined later in this .h file may be of more practical interest. template struct LUCES : public TF_ES { }; -//! \brief LUC signature scheme with appendix -//! \tparam STANDARD signature standard -//! \tparam H hash transformation -//! \details This class is here for historical and pedagogical interest. It has no practical advantages over other -//! trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes -//! defined later in this .h file may be of more practical interest. +/// \brief LUC signature scheme with appendix +/// \tparam STANDARD signature standard +/// \tparam H hash transformation +/// \details This class is here for historical and pedagogical interest. It has no practical advantages over other +/// trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes +/// defined later in this .h file may be of more practical interest. template struct LUCSS : public TF_SS { @@ -178,7 +178,7 @@ private: Integer m_p; }; -//! _ +/// _ class DL_BasePrecomputation_LUC : public DL_FixedBasePrecomputation { public: @@ -208,8 +208,8 @@ private: Integer m_g; }; -//! \class DL_GroupParameters_LUC -//! \brief LUC GroupParameters specialization +/// \class DL_GroupParameters_LUC +/// \brief LUC GroupParameters specialization class DL_GroupParameters_LUC : public DL_GroupParameters_IntegerBasedImpl { public: @@ -239,8 +239,8 @@ private: int GetFieldType() const {return 2;} }; -//! \class DL_GroupParameters_LUC_DefaultSafePrime -//! \brief GF(p) group parameters that default to safe primes +/// \class DL_GroupParameters_LUC_DefaultSafePrime +/// \brief GF(p) group parameters that default to safe primes class DL_GroupParameters_LUC_DefaultSafePrime : public DL_GroupParameters_LUC { public: @@ -250,8 +250,8 @@ protected: unsigned int GetDefaultSubgroupOrderSize(unsigned int modulusSize) const {return modulusSize-1;} }; -//! \class DL_Algorithm_LUC_HMP -//! \brief LUC HMP signature algorithm +/// \class DL_Algorithm_LUC_HMP +/// \brief LUC HMP signature algorithm class DL_Algorithm_LUC_HMP : public DL_ElgamalLikeSignatureAlgorithm { public: @@ -266,7 +266,7 @@ public: {return params.GetGroupOrder().ByteCount();} }; -//! \brief LUC signature keys +/// \brief LUC signature keys struct DL_SignatureKeys_LUC { typedef DL_GroupParameters_LUC GroupParameters; @@ -274,17 +274,17 @@ struct DL_SignatureKeys_LUC typedef DL_PrivateKey_GFP PrivateKey; }; -//! \brief LUC-HMP, based on "Digital signature schemes based on Lucas functions" by Patrick Horster, Markus Michels, Holger Petersen -//! \tparam H hash transformation -//! \details This class is here for historical and pedagogical interest. It has no practical advantages over other -//! trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes -//! defined later in this .h file may be of more practical interest. +/// \brief LUC-HMP, based on "Digital signature schemes based on Lucas functions" by Patrick Horster, Markus Michels, Holger Petersen +/// \tparam H hash transformation +/// \details This class is here for historical and pedagogical interest. It has no practical advantages over other +/// trapdoor functions and probably shouldn't be used in production software. The discrete log based LUC schemes +/// defined later in this .h file may be of more practical interest. template struct LUC_HMP : public DL_SS { }; -//! \brief LUC encryption keys +/// \brief LUC encryption keys struct DL_CryptoKeys_LUC { typedef DL_GroupParameters_LUC_DefaultSafePrime GroupParameters; @@ -292,14 +292,14 @@ struct DL_CryptoKeys_LUC typedef DL_PrivateKey_GFP PrivateKey; }; -//! \class LUC-IES -//! \brief LUC Integrated Encryption Scheme -//! \tparam COFACTOR_OPTION cofactor multiplication option -//! \tparam HASH HashTransformation derived class used for key drivation and MAC computation -//! \tparam DHAES_MODE flag indicating if the MAC includes additional context parameters such as u·V, v·U and label -//! \tparam LABEL_OCTETS flag indicating if the label size is specified in octets or bits -//! \sa CofactorMultiplicationOption -//! \since Crypto++ 4.0, Crypto++ 5.7 for Bouncy Castle and Botan compatibility +/// \class LUC-IES +/// \brief LUC Integrated Encryption Scheme +/// \tparam COFACTOR_OPTION cofactor multiplication option +/// \tparam HASH HashTransformation derived class used for key drivation and MAC computation +/// \tparam DHAES_MODE flag indicating if the MAC includes additional context parameters such as u·V, v·U and label +/// \tparam LABEL_OCTETS flag indicating if the label size is specified in octets or bits +/// \sa CofactorMultiplicationOption +/// \since Crypto++ 4.0, Crypto++ 5.7 for Bouncy Castle and Botan compatibility template struct LUC_IES : public DL_ES< @@ -314,7 +314,7 @@ struct LUC_IES // ******************************************************** -//! LUC-DH +/// LUC-DH typedef DH_Domain LUC_DH; NAMESPACE_END diff --git a/mars.h b/mars.h index da648526..120cb278 100644 --- a/mars.h +++ b/mars.h @@ -1,7 +1,7 @@ // mars.h - originally written and placed in the public domain by Wei Dai -//! \file mars.h -//! \brief Classes for the MARS block cipher (IBM AES submission) +/// \file mars.h +/// \brief Classes for the MARS block cipher (IBM AES submission) #ifndef CRYPTOPP_MARS_H #define CRYPTOPP_MARS_H @@ -11,16 +11,16 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class MARS_Info -//! \brief MARS block cipher information +/// \class MARS_Info +/// \brief MARS block cipher information struct MARS_Info : public FixedBlockSize<16>, public VariableKeyLength<16, 16, 56, 8> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "MARS";} }; -//! \class MARS -//! \brief MARS block cipher -//! \sa MARS +/// \class MARS +/// \brief MARS block cipher +/// \sa MARS class MARS : public MARS_Info, public BlockCipherDocumentation { class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl diff --git a/md4.h b/md4.h index 3eb327d5..8edb166d 100644 --- a/md4.h +++ b/md4.h @@ -7,7 +7,7 @@ NAMESPACE_BEGIN(CryptoPP) namespace Weak1 { -//! MD4 +/// MD4 /*! \warning MD4 is considered insecure, and should not be used unless you absolutely need it for compatibility. */ class MD4 : public IteratedHashWithStaticTransform diff --git a/md5.h b/md5.h index 99cb798a..2ae8af0d 100644 --- a/md5.h +++ b/md5.h @@ -7,10 +7,10 @@ NAMESPACE_BEGIN(CryptoPP) namespace Weak1 { -//! \class MD5 -//! \brief MD5 message digest -//! \sa MD5 -//! \since Crypto++ 1.0 +/// \class MD5 +/// \brief MD5 message digest +/// \sa MD5 +/// \since Crypto++ 1.0 class MD5 : public IteratedHashWithStaticTransform { public: diff --git a/mdc.h b/mdc.h index d5f1a881..18ddd2b7 100644 --- a/mdc.h +++ b/mdc.h @@ -3,8 +3,8 @@ #ifndef CRYPTOPP_MDC_H #define CRYPTOPP_MDC_H -//! \file mdc.h -//! \brief Classes for the MDC message digest +/// \file mdc.h +/// \brief Classes for the MDC message digest #include "seckey.h" #include "secblock.h" @@ -12,24 +12,24 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class MDC_Info -//! \tparam B BlockCipher derived class -//! \brief MDC_Info cipher information +/// \class MDC_Info +/// \tparam B BlockCipher derived class +/// \brief MDC_Info cipher information template struct MDC_Info : public FixedBlockSize, public FixedKeyLength { static std::string StaticAlgorithmName() {return std::string("MDC/")+B::StaticAlgorithmName();} }; -//! \brief MDC cipher -//! \tparam H HashTransformation derived class -//! \details MDC() is a construction by Peter Gutmann to turn an iterated hash function into a PRF -//! \sa MDC +/// \brief MDC cipher +/// \tparam H HashTransformation derived class +/// \details MDC() is a construction by Peter Gutmann to turn an iterated hash function into a PRF +/// \sa MDC template class MDC : public MDC_Info { - //! \class Enc - //! \brief MDC cipher encryption operation + /// \class Enc + /// \brief MDC cipher encryption operation class CRYPTOPP_NO_VTABLE Enc : public BlockCipherImpl > { typedef typename H::HashWordType HashWordType; diff --git a/mersenne.h b/mersenne.h index 369aa625..f8ed9fa1 100644 --- a/mersenne.h +++ b/mersenne.h @@ -1,10 +1,10 @@ // mersenne.h - written and placed in public domain by Jeffrey Walton. -//! \file mersenne.h -//! \brief Class file for Mersenne Twister -//! \warning MersenneTwister is suitable for Monte-Carlo simulations, where uniformaly distrubuted -//! numbers are required quickly. It should not be used for cryptographic purposes. -//! \since Crypto++ 5.6.3 +/// \file mersenne.h +/// \brief Class file for Mersenne Twister +/// \warning MersenneTwister is suitable for Monte-Carlo simulations, where uniformaly distrubuted +/// numbers are required quickly. It should not be used for cryptographic purposes. +/// \since Crypto++ 5.6.3 #ifndef CRYPTOPP_MERSENNE_TWISTER_H #define CRYPTOPP_MERSENNE_TWISTER_H @@ -14,18 +14,18 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class MersenneTwister -//! \brief Mersenne Twister class for Monte-Carlo simulations -//! \tparam K Magic constant -//! \tparam M Period parameter -//! \tparam N Size of the state vector -//! \tparam F Multiplier constant -//! \tparam S Initial seed -//! \details Provides the MersenneTwister implementation. The class is a header-only implementation. -//! \warning MersenneTwister is suitable for simulations, where uniformaly distrubuted numbers are -//! required quickly. It should not be used for cryptographic purposes. -//! \sa MT19937, MT19937ar -//! \since Crypto++ 5.6.3 +/// \class MersenneTwister +/// \brief Mersenne Twister class for Monte-Carlo simulations +/// \tparam K Magic constant +/// \tparam M Period parameter +/// \tparam N Size of the state vector +/// \tparam F Multiplier constant +/// \tparam S Initial seed +/// \details Provides the MersenneTwister implementation. The class is a header-only implementation. +/// \warning MersenneTwister is suitable for simulations, where uniformaly distrubuted numbers are +/// required quickly. It should not be used for cryptographic purposes. +/// \sa MT19937, MT19937ar +/// \since Crypto++ 5.6.3 template class MersenneTwister : public RandomNumberGenerator { @@ -34,10 +34,10 @@ public: ~MersenneTwister() {} - //! \brief Construct a Mersenne Twister - //! \param seed 32-bit seed - //! \details Defaults to template parameter S due to changing algorithm - //! parameters over time + /// \brief Construct a Mersenne Twister + /// \param seed 32-bit seed + /// \details Defaults to template parameter S due to changing algorithm + /// parameters over time MersenneTwister(word32 seed = S) : m_seed(seed), m_idx(N) { Reset(seed); @@ -45,11 +45,11 @@ public: bool CanIncorporateEntropy() const {return true;} - //! \brief Update RNG state with additional unpredictable values - //! \param input the entropy to add to the generator - //! \param length the size of the input buffer - //! \details MersenneTwister uses the first 32-bits of input to reseed the - //! generator. If fewer bytes are provided, then the seed is padded with 0's. + /// \brief Update RNG state with additional unpredictable values + /// \param input the entropy to add to the generator + /// \param length the size of the input buffer + /// \details MersenneTwister uses the first 32-bits of input to reseed the + /// generator. If fewer bytes are provided, then the seed is padded with 0's. void IncorporateEntropy(const byte *input, size_t length) { word32 temp = 0; @@ -60,13 +60,13 @@ public: SecureWipeArray(&temp, 1); } - //! \brief Generate random array of bytes - //! \param output byte buffer - //! \param size length of the buffer, in bytes - //! \details Bytes are written to output in big endian order. If output length - //! is not a multiple of word32, then unused bytes are not accumulated for subsequent - //! calls to GenerateBlock. Rather, the unused tail bytes are discarded, and the - //! stream is continued at the next word32 boundary from the state array. + /// \brief Generate random array of bytes + /// \param output byte buffer + /// \param size length of the buffer, in bytes + /// \details Bytes are written to output in big endian order. If output length + /// is not a multiple of word32, then unused bytes are not accumulated for subsequent + /// calls to GenerateBlock. Rather, the unused tail bytes are discarded, and the + /// stream is continued at the next word32 boundary from the state array. void GenerateBlock(byte *output, size_t size) { // Handle word32 size blocks @@ -100,10 +100,10 @@ public: SecureWipeArray(&temp, 1); } - //! \brief Generate a random 32-bit word in the range min to max, inclusive - //! \returns random 32-bit word in the range min to max, inclusive - //! \details If the 32-bit candidate is not within the range, then it is discarded - //! and a new candidate is used. + /// \brief Generate a random 32-bit word in the range min to max, inclusive + /// \returns random 32-bit word in the range min to max, inclusive + /// \details If the 32-bit candidate is not within the range, then it is discarded + /// and a new candidate is used. word32 GenerateWord32(word32 min=0, word32 max=0xffffffffL) { const word32 range = max-min; @@ -120,12 +120,12 @@ public: return value+min; } - //! \brief Generate and discard n bytes - //! \param n the number of bytes to discard, rounded up to a word32 size - //! \details If n is not a multiple of word32, then unused bytes are - //! not accumulated for subsequent calls to GenerateBlock. Rather, the unused - //! tail bytes are discarded, and the stream is continued at the next - //! word32 boundary from the state array. + /// \brief Generate and discard n bytes + /// \param n the number of bytes to discard, rounded up to a word32 size + /// \details If n is not a multiple of word32, then unused bytes are + /// not accumulated for subsequent calls to GenerateBlock. Rather, the unused + /// tail bytes are discarded, and the stream is continued at the next + /// word32 boundary from the state array. void DiscardBytes(size_t n) { for(size_t i=0; i < RoundUpToMultipleOf(n, 4U); i++) @@ -144,10 +144,10 @@ protected: m_state[i] = word32(F * (m_state[i-1] ^ (m_state[i-1] >> 30)) + i); } - //! \brief Returns the next 32-bit word from the state array - //! \returns the next 32-bit word from the state array - //! \details fetches the next word frm the state array, performs bit operations on - //! it, and then returns the value to the caller. + /// \brief Returns the next 32-bit word from the state array + /// \returns the next 32-bit word from the state array + /// \details fetches the next word frm the state array, performs bit operations on + /// it, and then returns the value to the caller. word32 NextMersenneWord() { if (m_idx >= N) { Twist(); } @@ -161,7 +161,7 @@ protected: return temp ^ (temp >> 18); } - //! \brief Performs the twist operaton on the state array + /// \brief Performs the twist operaton on the state array void Twist() { static const word32 magic[2]={0x0UL, K}; @@ -192,33 +192,33 @@ protected: private: - //! \brief 32-bit word state array of size N + /// \brief 32-bit word state array of size N FixedSizeSecBlock m_state; - //! \brief the value used to seed the generator + /// \brief the value used to seed the generator word32 m_seed; - //! \brief the current index into the state array + /// \brief the current index into the state array word32 m_idx; }; -//! \class MT19937 -//! \brief Original MT19937 generator provided in the ACM paper. -//! \details MT19937 uses 4537 as default initial seed. -//! \sa MT19937ar, Mersenne twister: -//! a 623-dimensionally equidistributed uniform pseudo-random number generator -//! \since Crypto++ 5.6.3 +/// \class MT19937 +/// \brief Original MT19937 generator provided in the ACM paper. +/// \details MT19937 uses 4537 as default initial seed. +/// \sa MT19937ar, Mersenne twister: +/// a 623-dimensionally equidistributed uniform pseudo-random number generator +/// \since Crypto++ 5.6.3 #if CRYPTOPP_DOXYGEN_PROCESSING class MT19937 : public MersenneTwister<0x9908B0DF /*2567483615*/, 397, 624, 0x10DCD /*69069*/, 4537> {}; #else typedef MersenneTwister<0x9908B0DF /*2567483615*/, 397, 624, 0x10DCD /*69069*/, 4537> MT19937; #endif -//! \class MT19937ar -//! \brief Updated MT19937 generator adapted to provide an array for initialization. -//! \details MT19937 uses 5489 as default initial seed. Use this generator when interoperating with C++11's -//! mt19937 class. -//! \sa MT19937, Mersenne Twister -//! with improved initialization -//! \since Crypto++ 5.6.3 +/// \class MT19937ar +/// \brief Updated MT19937 generator adapted to provide an array for initialization. +/// \details MT19937 uses 5489 as default initial seed. Use this generator when interoperating with C++11's +/// mt19937 class. +/// \sa MT19937, Mersenne Twister +/// with improved initialization +/// \since Crypto++ 5.6.3 #if CRYPTOPP_DOXYGEN_PROCESSING class MT19937ar : public MersenneTwister<0x9908B0DF /*2567483615*/, 397, 624, 0x6C078965 /*1812433253*/, 5489> {}; #else diff --git a/misc.h b/misc.h index ff868058..ce09d366 100644 --- a/misc.h +++ b/misc.h @@ -1,7 +1,7 @@ // misc.h - originally written and placed in the public domain by Wei Dai -//! \file misc.h -//! \brief Utility functions for the Crypto++ library. +/// \file misc.h +/// \brief Utility functions for the Crypto++ library. #ifndef CRYPTOPP_MISC_H #define CRYPTOPP_MISC_H @@ -73,15 +73,15 @@ #endif // CRYPTOPP_DOXYGEN_PROCESSING #if CRYPTOPP_DOXYGEN_PROCESSING -//! \brief The maximum value of a machine word -//! \details SIZE_MAX provides the maximum value of a machine word. The value is -//! \p 0xffffffff on 32-bit machines, and \p 0xffffffffffffffff on 64-bit machines. -//! Internally, SIZE_MAX is defined as __SIZE_MAX__ if __SIZE_MAX__ is defined. If not -//! defined, then SIZE_T_MAX is tried. If neither __SIZE_MAX__ nor SIZE_T_MAX is -//! is defined, the library uses std::numeric_limits::max(). The library -//! prefers __SIZE_MAX__ because its a constexpr that is optimized well -//! by all compilers. std::numeric_limits::max() is \a not a constexpr, -//! and it is \a not always optimized well. +/// \brief The maximum value of a machine word +/// \details SIZE_MAX provides the maximum value of a machine word. The value is +/// \p 0xffffffff on 32-bit machines, and \p 0xffffffffffffffff on 64-bit machines. +/// Internally, SIZE_MAX is defined as __SIZE_MAX__ if __SIZE_MAX__ is defined. If not +/// defined, then SIZE_T_MAX is tried. If neither __SIZE_MAX__ nor SIZE_T_MAX is +/// is defined, the library uses std::numeric_limits::max(). The library +/// prefers __SIZE_MAX__ because its a constexpr that is optimized well +/// by all compilers. std::numeric_limits::max() is \a not a constexpr, +/// and it is \a not always optimized well. # define SIZE_MAX ... #else // Its amazing portability problems still plague this simple concept in 2015. @@ -138,9 +138,9 @@ class Integer; // ************** compile-time assertion *************** #if CRYPTOPP_DOXYGEN_PROCESSING -//! \brief Compile time assertion -//! \param expr the expression to evaluate -//! \details Asserts the expression expr though a dummy struct. +/// \brief Compile time assertion +/// \param expr the expression to evaluate +/// \details Asserts the expression expr though a dummy struct. #define CRYPTOPP_COMPILE_ASSERT(expr) { ... } #else // CRYPTOPP_DOXYGEN_PROCESSING template @@ -171,13 +171,13 @@ struct CompileAssert // ************** count elements in an array *************** #if CRYPTOPP_DOXYGEN_PROCESSING -//! \brief Counts elements in an array -//! \param arr an array of elements -//! \details COUNTOF counts elements in an array. On Windows COUNTOF(x) is defined -//! to _countof(x) to ensure correct results for pointers. -//! \note COUNTOF does not produce correct results with pointers, and an array must be used. -//! sizeof(x)/sizeof(x[0]) suffers the same problem. The risk is eliminated by using -//! _countof(x) on Windows. Windows will provide the immunity for other platforms. +/// \brief Counts elements in an array +/// \param arr an array of elements +/// \details COUNTOF counts elements in an array. On Windows COUNTOF(x) is defined +/// to _countof(x) to ensure correct results for pointers. +/// \note COUNTOF does not produce correct results with pointers, and an array must be used. +/// sizeof(x)/sizeof(x[0]) suffers the same problem. The risk is eliminated by using +/// _countof(x) on Windows. Windows will provide the immunity for other platforms. # define COUNTOF(arr) #else // VS2005 added _countof @@ -192,8 +192,8 @@ struct CompileAssert // ************** misc classes *************** -//! \brief An Empty class -//! \details The Empty class can be used as a template parameter BASE when no base class exists. +/// \brief An Empty class +/// \details The Empty class can be used as a template parameter BASE when no base class exists. class CRYPTOPP_DLL Empty { }; @@ -210,10 +210,10 @@ class CRYPTOPP_NO_VTABLE ThreeBases : public BASE1, public BASE2, public BASE3 }; #endif // CRYPTOPP_DOXYGEN_PROCESSING -//! \class ObjectHolder -//! \tparam T class or type -//! \brief Uses encapsulation to hide an object in derived classes -//! \details The object T is declared as protected. +/// \class ObjectHolder +/// \tparam T class or type +/// \brief Uses encapsulation to hide an object in derived classes +/// \details The object T is declared as protected. template class ObjectHolder { @@ -221,12 +221,12 @@ protected: T m_object; }; -//! \class NotCopyable -//! \brief Ensures an object is not copyable -//! \details NotCopyable ensures an object is not copyable by making the -//! copy constructor and assignment operator private. Deleters are not -//! used under C++11. -//! \sa Clonable class +/// \class NotCopyable +/// \brief Ensures an object is not copyable +/// \details NotCopyable ensures an object is not copyable by making the +/// copy constructor and assignment operator private. Deleters are not +/// used under C++11. +/// \sa Clonable class class NotCopyable { public: @@ -236,10 +236,10 @@ private: void operator=(const NotCopyable &); }; -//! \class NewObject -//! \brief An object factory function -//! \tparam T class or type -//! \details NewObject overloads operator()(). +/// \class NewObject +/// \brief An object factory function +/// \tparam T class or type +/// \details NewObject overloads operator()(). template struct NewObject { @@ -247,14 +247,14 @@ struct NewObject }; #if CRYPTOPP_DOXYGEN_PROCESSING -//! \brief A memory barrier -//! \details MEMORY_BARRIER attempts to ensure reads and writes are completed -//! in the absence of a language synchronization point. It is used by the -//! Singleton class if the compiler supports it. The barrier is provided at the -//! customary places in a double-checked initialization. -//! \details Internally, MEMORY_BARRIER uses std::atomic_thread_fence if -//! C++11 atomics are available. Otherwise, intrinsic(_ReadWriteBarrier), -//! _ReadWriteBarrier() or __asm__("" ::: "memory") is used. +/// \brief A memory barrier +/// \details MEMORY_BARRIER attempts to ensure reads and writes are completed +/// in the absence of a language synchronization point. It is used by the +/// Singleton class if the compiler supports it. The barrier is provided at the +/// customary places in a double-checked initialization. +/// \details Internally, MEMORY_BARRIER uses std::atomic_thread_fence if +/// C++11 atomics are available. Otherwise, intrinsic(_ReadWriteBarrier), +/// _ReadWriteBarrier() or __asm__("" ::: "memory") is used. #define MEMORY_BARRIER ... #else #if defined(CRYPTOPP_CXX11_ATOMICS) @@ -271,25 +271,25 @@ struct NewObject #endif #endif // CRYPTOPP_DOXYGEN_PROCESSING -//! \brief Restricts the instantiation of a class to one static object without locks -//! \tparam T the class or type -//! \tparam F the object factory for T -//! \tparam instance an instance counter for the class object -//! \details This class safely initializes a static object in a multithreaded environment. For C++03 -//! and below it will do so without using locks for portability. If two threads call Ref() at the same -//! time, they may get back different references, and one object may end up being memory leaked. This -//! is by design and it avoids a subltle initialization problem ina multithreaded environment with thread -//! local storage on early Windows platforms, like Windows XP and Windows 2003. -//! \details For C++11 and above, a standard double-checked locking pattern with thread fences -//! are used. The locks and fences are standard and do not hinder portability. -//! \details Microsoft's C++11 implementation provides the necessary primitive support on Windows Vista and -//! above when using Visual Studio 2015 (cl.exe version 19.00). If C++11 is desired, you should -//! set WINVER or _WIN32_WINNT to 0x600 (or above), and compile with Visual Studio 2015. -//! \sa Double-Checked Locking -//! is Fixed In C++11, Dynamic -//! Initialization and Destruction with Concurrency and -//! Thread Local Storage (TLS) on MSDN. -//! \since Crypto++ 5.2 +/// \brief Restricts the instantiation of a class to one static object without locks +/// \tparam T the class or type +/// \tparam F the object factory for T +/// \tparam instance an instance counter for the class object +/// \details This class safely initializes a static object in a multithreaded environment. For C++03 +/// and below it will do so without using locks for portability. If two threads call Ref() at the same +/// time, they may get back different references, and one object may end up being memory leaked. This +/// is by design and it avoids a subltle initialization problem ina multithreaded environment with thread +/// local storage on early Windows platforms, like Windows XP and Windows 2003. +/// \details For C++11 and above, a standard double-checked locking pattern with thread fences +/// are used. The locks and fences are standard and do not hinder portability. +/// \details Microsoft's C++11 implementation provides the necessary primitive support on Windows Vista and +/// above when using Visual Studio 2015 (cl.exe version 19.00). If C++11 is desired, you should +/// set WINVER or _WIN32_WINNT to 0x600 (or above), and compile with Visual Studio 2015. +/// \sa Double-Checked Locking +/// is Fixed In C++11, Dynamic +/// Initialization and Destruction with Concurrency and +/// Thread Local Storage (TLS) on MSDN. +/// \since Crypto++ 5.2 template , int instance=0> class Singleton { @@ -303,14 +303,14 @@ private: F m_objectFactory; }; -//! \brief Return a reference to the inner Singleton object -//! \tparam T the class or type -//! \tparam F the object factory for T -//! \tparam instance an instance counter for the class object -//! \details Ref() is used to create the object using the object factory. The -//! object is only created once with the limitations discussed in the class documentation. -//! \sa Double-Checked Locking is Fixed In C++11 -//! \since Crypto++ 5.2 +/// \brief Return a reference to the inner Singleton object +/// \tparam T the class or type +/// \tparam F the object factory for T +/// \tparam instance an instance counter for the class object +/// \details Ref() is used to create the object using the object factory. The +/// object is only created once with the limitations discussed in the class documentation. +/// \sa Double-Checked Locking is Fixed In C++11 +/// \since Crypto++ 5.2 template const T & Singleton::Ref(CRYPTOPP_NOINLINE_DOTDOTDOT) const { @@ -365,24 +365,24 @@ template #if (!__STDC_WANT_SECURE_LIB__ && !defined(_MEMORY_S_DEFINED)) || defined(CRYPTOPP_WANT_SECURE_LIB) -//! \brief Bounds checking replacement for memcpy() -//! \param dest pointer to the desination memory block -//! \param sizeInBytes the size of the desination memory block, in bytes -//! \param src pointer to the source memory block -//! \param count the size of the source memory block, in bytes -//! \throws InvalidArgument -//! \details ISO/IEC TR-24772 provides bounds checking interfaces for potentially -//! unsafe functions like memcpy(), strcpy() and memmove(). However, -//! not all standard libraries provides them, like Glibc. The library's -//! memcpy_s() is a near-drop in replacement. Its only a near-replacement -//! because the library's version throws an InvalidArgument on a bounds violation. -//! \details memcpy_s() and memmove_s() are guarded by __STDC_WANT_SECURE_LIB__. -//! If __STDC_WANT_SECURE_LIB__ is \a not defined or defined to 0, then the library -//! makes memcpy_s() and memmove_s() available. The library will also optionally -//! make the symbols available if CRYPTOPP_WANT_SECURE_LIB is defined. -//! CRYPTOPP_WANT_SECURE_LIB is in config.h, but it is disabled by default. -//! \details memcpy_s() will assert the pointers src and dest are not NULL -//! in debug builds. Passing NULL for either pointer is undefined behavior. +/// \brief Bounds checking replacement for memcpy() +/// \param dest pointer to the desination memory block +/// \param sizeInBytes the size of the desination memory block, in bytes +/// \param src pointer to the source memory block +/// \param count the size of the source memory block, in bytes +/// \throws InvalidArgument +/// \details ISO/IEC TR-24772 provides bounds checking interfaces for potentially +/// unsafe functions like memcpy(), strcpy() and memmove(). However, +/// not all standard libraries provides them, like Glibc. The library's +/// memcpy_s() is a near-drop in replacement. Its only a near-replacement +/// because the library's version throws an InvalidArgument on a bounds violation. +/// \details memcpy_s() and memmove_s() are guarded by __STDC_WANT_SECURE_LIB__. +/// If __STDC_WANT_SECURE_LIB__ is \a not defined or defined to 0, then the library +/// makes memcpy_s() and memmove_s() available. The library will also optionally +/// make the symbols available if CRYPTOPP_WANT_SECURE_LIB is defined. +/// CRYPTOPP_WANT_SECURE_LIB is in config.h, but it is disabled by default. +/// \details memcpy_s() will assert the pointers src and dest are not NULL +/// in debug builds. Passing NULL for either pointer is undefined behavior. inline void memcpy_s(void *dest, size_t sizeInBytes, const void *src, size_t count) { // Safer functions on Windows for C&A, http://github.com/weidai11/cryptopp/issues/55 @@ -407,24 +407,24 @@ inline void memcpy_s(void *dest, size_t sizeInBytes, const void *src, size_t cou #endif } -//! \brief Bounds checking replacement for memmove() -//! \param dest pointer to the desination memory block -//! \param sizeInBytes the size of the desination memory block, in bytes -//! \param src pointer to the source memory block -//! \param count the size of the source memory block, in bytes -//! \throws InvalidArgument -//! \details ISO/IEC TR-24772 provides bounds checking interfaces for potentially -//! unsafe functions like memcpy(), strcpy() and memmove(). However, -//! not all standard libraries provides them, like Glibc. The library's -//! memmove_s() is a near-drop in replacement. Its only a near-replacement -//! because the library's version throws an InvalidArgument on a bounds violation. -//! \details memcpy_s() and memmove_s() are guarded by __STDC_WANT_SECURE_LIB__. -//! If __STDC_WANT_SECURE_LIB__ is \a not defined or defined to 0, then the library -//! makes memcpy_s() and memmove_s() available. The library will also optionally -//! make the symbols available if CRYPTOPP_WANT_SECURE_LIB is defined. -//! CRYPTOPP_WANT_SECURE_LIB is in config.h, but it is disabled by default. -//! \details memmove_s() will assert the pointers src and dest are not NULL -//! in debug builds. Passing NULL for either pointer is undefined behavior. +/// \brief Bounds checking replacement for memmove() +/// \param dest pointer to the desination memory block +/// \param sizeInBytes the size of the desination memory block, in bytes +/// \param src pointer to the source memory block +/// \param count the size of the source memory block, in bytes +/// \throws InvalidArgument +/// \details ISO/IEC TR-24772 provides bounds checking interfaces for potentially +/// unsafe functions like memcpy(), strcpy() and memmove(). However, +/// not all standard libraries provides them, like Glibc. The library's +/// memmove_s() is a near-drop in replacement. Its only a near-replacement +/// because the library's version throws an InvalidArgument on a bounds violation. +/// \details memcpy_s() and memmove_s() are guarded by __STDC_WANT_SECURE_LIB__. +/// If __STDC_WANT_SECURE_LIB__ is \a not defined or defined to 0, then the library +/// makes memcpy_s() and memmove_s() available. The library will also optionally +/// make the symbols available if CRYPTOPP_WANT_SECURE_LIB is defined. +/// CRYPTOPP_WANT_SECURE_LIB is in config.h, but it is disabled by default. +/// \details memmove_s() will assert the pointers src and dest are not NULL +/// in debug builds. Passing NULL for either pointer is undefined behavior. inline void memmove_s(void *dest, size_t sizeInBytes, const void *src, size_t count) { // Safer functions on Windows for C&A, http://github.com/weidai11/cryptopp/issues/55 @@ -457,15 +457,15 @@ inline void memmove_s(void *dest, size_t sizeInBytes, const void *src, size_t co #endif // __STDC_WANT_SECURE_LIB__ -//! \brief Swaps two variables which are arrays -//! \tparam T class or type -//! \param a the first value -//! \param b the second value -//! \details C++03 does not provide support for std::swap(__m128i a, __m128i b) -//! because __m128i is an unsigned long long[2]. Most compilers -//! support it out of the box, but Sun Studio C++ compilers 12.2 and 12.3 do not. -//! \sa How to swap two __m128i variables -//! in C++03 given its an opaque type and an array? on Stack Overflow. +/// \brief Swaps two variables which are arrays +/// \tparam T class or type +/// \param a the first value +/// \param b the second value +/// \details C++03 does not provide support for std::swap(__m128i a, __m128i b) +/// because __m128i is an unsigned long long[2]. Most compilers +/// support it out of the box, but Sun Studio C++ compilers 12.2 and 12.3 do not. +/// \sa How to swap two __m128i variables +/// in C++03 given its an opaque type and an array? on Stack Overflow. template inline void vec_swap(T& a, T& b) { @@ -473,12 +473,12 @@ inline void vec_swap(T& a, T& b) t=a, a=b, b=t; } -//! \brief Memory block initializer and eraser that attempts to survive optimizations -//! \param ptr pointer to the memory block being written -//! \param value the integer value to write for each byte -//! \param num the size of the source memory block, in bytes -//! \details Internally the function calls memset with the value value, and receives the -//! return value from memset as a volatile pointer. +/// \brief Memory block initializer and eraser that attempts to survive optimizations +/// \param ptr pointer to the memory block being written +/// \param value the integer value to write for each byte +/// \param num the size of the source memory block, in bytes +/// \details Internally the function calls memset with the value value, and receives the +/// return value from memset as a volatile pointer. inline void * memset_z(void *ptr, int value, size_t num) { // avoid extranous warning on GCC 4.3.2 Ubuntu 8.10 @@ -490,23 +490,23 @@ inline void * memset_z(void *ptr, int value, size_t num) return const_cast(x); } -//! \brief Replacement function for std::min -//! \tparam T class or type -//! \param a the first value -//! \param b the second value -//! \returns the minimum value based on a comparison of b \< a using operator\< -//! \details STDMIN was provided because the library could not easily use std::min or std::max in Windows or Cygwin 1.1.0 +/// \brief Replacement function for std::min +/// \tparam T class or type +/// \param a the first value +/// \param b the second value +/// \returns the minimum value based on a comparison of b \< a using operator\< +/// \details STDMIN was provided because the library could not easily use std::min or std::max in Windows or Cygwin 1.1.0 template inline const T& STDMIN(const T& a, const T& b) { return b < a ? b : a; } -//! \brief Replacement function for std::max -//! \tparam T class or type -//! \param a the first value -//! \param b the second value -//! \returns the minimum value based on a comparison of a \< b using operator\< -//! \details STDMAX was provided because the library could not easily use std::min or std::max in Windows or Cygwin 1.1.0 +/// \brief Replacement function for std::max +/// \tparam T class or type +/// \param a the first value +/// \param b the second value +/// \returns the minimum value based on a comparison of a \< b using operator\< +/// \details STDMAX was provided because the library could not easily use std::min or std::max in Windows or Cygwin 1.1.0 template inline const T& STDMAX(const T& a, const T& b) { return a < b ? b : a; @@ -527,13 +527,13 @@ template inline const T& STDMAX(const T& a, const T& b) # endif #endif -//! \brief Safe comparison of values that could be neagtive and incorrectly promoted -//! \tparam T1 class or type -//! \tparam T2 class or type -//! \param a the first value -//! \param b the second value -//! \returns the minimum value based on a comparison a and b using operator<. -//! \details The comparison b \< a is performed and the value returned is a's type T1. +/// \brief Safe comparison of values that could be neagtive and incorrectly promoted +/// \tparam T1 class or type +/// \tparam T2 class or type +/// \param a the first value +/// \param b the second value +/// \returns the minimum value based on a comparison a and b using operator<. +/// \details The comparison b \< a is performed and the value returned is a's type T1. template inline const T1 UnsignedMin(const T1& a, const T2& b) { CRYPTOPP_COMPILE_ASSERT((sizeof(T1)<=sizeof(T2) && T2(-1)>0) || (sizeof(T1)>sizeof(T2) && T1(-1)>0)); @@ -543,12 +543,12 @@ template inline const T1 UnsignedMin(const T1& a, const T2& return (T1)b < a ? (T1)b : a; } -//! \brief Tests whether a conversion from -> to is safe to perform -//! \tparam T1 class or type -//! \tparam T2 class or type -//! \param from the first value -//! \param to the second value -//! \returns true if its safe to convert from into to, false otherwise. +/// \brief Tests whether a conversion from -> to is safe to perform +/// \tparam T1 class or type +/// \tparam T2 class or type +/// \param from the first value +/// \param to the second value +/// \returns true if its safe to convert from into to, false otherwise. template inline bool SafeConvert(T1 from, T2 &to) { @@ -558,11 +558,11 @@ inline bool SafeConvert(T1 from, T2 &to) return true; } -//! \brief Converts a value to a string -//! \tparam T class or type -//! \param value the value to convert -//! \param base the base to use during the conversion -//! \returns the string representation of value in base. +/// \brief Converts a value to a string +/// \tparam T class or type +/// \param value the value to convert +/// \param base the base to use during the conversion +/// \returns the string representation of value in base. template std::string IntToString(T value, unsigned int base = 10) { @@ -593,34 +593,34 @@ std::string IntToString(T value, unsigned int base = 10) return result; } -//! \brief Converts an unsigned value to a string -//! \param value the value to convert -//! \param base the base to use during the conversion -//! \returns the string representation of value in base. -//! \details this template function specialization was added to suppress -//! Coverity findings on IntToString() with unsigned types. +/// \brief Converts an unsigned value to a string +/// \param value the value to convert +/// \param base the base to use during the conversion +/// \returns the string representation of value in base. +/// \details this template function specialization was added to suppress +/// Coverity findings on IntToString() with unsigned types. template <> CRYPTOPP_DLL std::string IntToString(word64 value, unsigned int base); -//! \brief Converts an Integer to a string -//! \param value the Integer to convert -//! \param base the base to use during the conversion -//! \returns the string representation of value in base. -//! \details This is a template specialization of IntToString(). Use it -//! like IntToString(): -//! 
-//!   // Print integer in base 10
-//!   Integer n...
-//!   std::string s = IntToString(n, 10);
-//!
-//! \details The string is presented with lowercase letters by default. A -//! hack is available to switch to uppercase letters without modifying -//! the function signature. -//! 
-//!   // Print integer in base 16, uppercase letters
-//!   Integer n...
-//!   const unsigned int UPPER = (1 << 31);
-//!   std::string s = IntToString(n, (UPPER | 16));
+/// \brief Converts an Integer to a string +/// \param value the Integer to convert +/// \param base the base to use during the conversion +/// \returns the string representation of value in base. +/// \details This is a template specialization of IntToString(). Use it +/// like IntToString(): +/// 
+///   // Print integer in base 10
+///   Integer n...
+///   std::string s = IntToString(n, 10);
+///
+/// \details The string is presented with lowercase letters by default. A +/// hack is available to switch to uppercase letters without modifying +/// the function signature. +/// 
+///   // Print integer in base 16, uppercase letters
+///   Integer n...
+///   const unsigned int UPPER = (1 << 31);
+///   std::string s = IntToString(n, (UPPER | 16));
template <> CRYPTOPP_DLL std::string IntToString(Integer value, unsigned int base); @@ -642,10 +642,10 @@ std::string IntToString(Integer value, unsigned int base); #define CRYPTOPP_GET_BYTE_AS_BYTE(x, y) byte((x)>>(8*(y))) -//! \brief Returns the parity of a value -//! \tparam T class or type -//! \param value the value to provide the parity -//! \returns 1 if the number 1-bits in the value is odd, 0 otherwise +/// \brief Returns the parity of a value +/// \tparam T class or type +/// \param value the value to provide the parity +/// \returns 1 if the number 1-bits in the value is odd, 0 otherwise template unsigned int Parity(T value) { @@ -654,10 +654,10 @@ unsigned int Parity(T value) return (unsigned int)value&1; } -//! \brief Returns the number of 8-bit bytes or octets required for a value -//! \tparam T class or type -//! \param value the value to test -//! \returns the minimum number of 8-bit bytes or octets required to represent a value +/// \brief Returns the number of 8-bit bytes or octets required for a value +/// \tparam T class or type +/// \param value the value to test +/// \returns the minimum number of 8-bit bytes or octets required to represent a value template unsigned int BytePrecision(const T &value) { @@ -677,10 +677,10 @@ unsigned int BytePrecision(const T &value) return h/8; } -//! \brief Returns the number of bits required for a value -//! \tparam T class or type -//! \param value the value to test -//! \returns the maximum number of bits required to represent a value. +/// \brief Returns the number of bits required for a value +/// \tparam T class or type +/// \param value the value to test +/// \returns the maximum number of bits required to represent a value. template unsigned int BitPrecision(const T &value) { @@ -701,12 +701,12 @@ unsigned int BitPrecision(const T &value) return h; } -//! Determines the number of trailing 0-bits in a value -//! \param v the 32-bit value to test -//! \returns the number of trailing 0-bits in v, starting at the least significant bit position -//! \details TrailingZeros returns the number of trailing 0-bits in v, starting at the least -//! significant bit position. The return value is undefined if there are no 1-bits set in the value v. -//! \note The function does \a not return 0 if no 1-bits are set because 0 collides with a 1-bit at the 0-th position. +/// Determines the number of trailing 0-bits in a value +/// \param v the 32-bit value to test +/// \returns the number of trailing 0-bits in v, starting at the least significant bit position +/// \details TrailingZeros returns the number of trailing 0-bits in v, starting at the least +/// significant bit position. The return value is undefined if there are no 1-bits set in the value v. +/// \note The function does \a not return 0 if no 1-bits are set because 0 collides with a 1-bit at the 0-th position. inline unsigned int TrailingZeros(word32 v) { // GCC 4.7 and VS2012 provides tzcnt on AVX2/BMI enabled processors @@ -732,12 +732,12 @@ inline unsigned int TrailingZeros(word32 v) #endif } -//! Determines the number of trailing 0-bits in a value -//! \param v the 64-bit value to test -//! \returns the number of trailing 0-bits in v, starting at the least significant bit position -//! \details TrailingZeros returns the number of trailing 0-bits in v, starting at the least -//! significant bit position. The return value is undefined if there are no 1-bits set in the value v. -//! \note The function does \a not return 0 if no 1-bits are set because 0 collides with a 1-bit at the 0-th position. +/// Determines the number of trailing 0-bits in a value +/// \param v the 64-bit value to test +/// \returns the number of trailing 0-bits in v, starting at the least significant bit position +/// \details TrailingZeros returns the number of trailing 0-bits in v, starting at the least +/// significant bit position. The return value is undefined if there are no 1-bits set in the value v. +/// \note The function does \a not return 0 if no 1-bits are set because 0 collides with a 1-bit at the 0-th position. inline unsigned int TrailingZeros(word64 v) { // GCC 4.7 and VS2012 provides tzcnt on AVX2/BMI enabled processors @@ -757,14 +757,14 @@ inline unsigned int TrailingZeros(word64 v) #endif } -//! \brief Truncates the value to the specified number of bits. -//! \tparam T class or type -//! \param value the value to truncate or mask -//! \param bits the number of bits to truncate or mask -//! \returns the value truncated to the specified number of bits, starting at the least -//! significant bit position -//! \details This function masks the low-order bits of value and returns the result. The -//! mask is created with (1 << bits) - 1. +/// \brief Truncates the value to the specified number of bits. +/// \tparam T class or type +/// \param value the value to truncate or mask +/// \param bits the number of bits to truncate or mask +/// \returns the value truncated to the specified number of bits, starting at the least +/// significant bit position +/// \details This function masks the low-order bits of value and returns the result. The +/// mask is created with (1 << bits) - 1. template inline T Crop(T value, size_t bits) { @@ -774,78 +774,78 @@ inline T Crop(T value, size_t bits) return value; } -//! \brief Returns the number of 8-bit bytes or octets required for the specified number of bits -//! \param bitCount the number of bits -//! \returns the minimum number of 8-bit bytes or octets required by bitCount -//! \details BitsToBytes is effectively a ceiling function based on 8-bit bytes. +/// \brief Returns the number of 8-bit bytes or octets required for the specified number of bits +/// \param bitCount the number of bits +/// \returns the minimum number of 8-bit bytes or octets required by bitCount +/// \details BitsToBytes is effectively a ceiling function based on 8-bit bytes. inline size_t BitsToBytes(size_t bitCount) { return ((bitCount+7)/(8)); } -//! \brief Returns the number of words required for the specified number of bytes -//! \param byteCount the number of bytes -//! \returns the minimum number of words required by byteCount -//! \details BytesToWords is effectively a ceiling function based on WORD_SIZE. -//! WORD_SIZE is defined in config.h +/// \brief Returns the number of words required for the specified number of bytes +/// \param byteCount the number of bytes +/// \returns the minimum number of words required by byteCount +/// \details BytesToWords is effectively a ceiling function based on WORD_SIZE. +/// WORD_SIZE is defined in config.h inline size_t BytesToWords(size_t byteCount) { return ((byteCount+WORD_SIZE-1)/WORD_SIZE); } -//! \brief Returns the number of words required for the specified number of bits -//! \param bitCount the number of bits -//! \returns the minimum number of words required by bitCount -//! \details BitsToWords is effectively a ceiling function based on WORD_BITS. -//! WORD_BITS is defined in config.h +/// \brief Returns the number of words required for the specified number of bits +/// \param bitCount the number of bits +/// \returns the minimum number of words required by bitCount +/// \details BitsToWords is effectively a ceiling function based on WORD_BITS. +/// WORD_BITS is defined in config.h inline size_t BitsToWords(size_t bitCount) { return ((bitCount+WORD_BITS-1)/(WORD_BITS)); } -//! \brief Returns the number of double words required for the specified number of bits -//! \param bitCount the number of bits -//! \returns the minimum number of double words required by bitCount -//! \details BitsToDwords is effectively a ceiling function based on 2*WORD_BITS. -//! WORD_BITS is defined in config.h +/// \brief Returns the number of double words required for the specified number of bits +/// \param bitCount the number of bits +/// \returns the minimum number of double words required by bitCount +/// \details BitsToDwords is effectively a ceiling function based on 2*WORD_BITS. +/// WORD_BITS is defined in config.h inline size_t BitsToDwords(size_t bitCount) { return ((bitCount+2*WORD_BITS-1)/(2*WORD_BITS)); } -//! Performs an XOR of a buffer with a mask -//! \param buf the buffer to XOR with the mask -//! \param mask the mask to XOR with the buffer -//! \param count the size of the buffers, in bytes -//! \details The function effectively visits each element in the buffers and performs -//! buf[i] ^= mask[i]. buf and mask must be of equal size. +/// Performs an XOR of a buffer with a mask +/// \param buf the buffer to XOR with the mask +/// \param mask the mask to XOR with the buffer +/// \param count the size of the buffers, in bytes +/// \details The function effectively visits each element in the buffers and performs +/// buf[i] ^= mask[i]. buf and mask must be of equal size. CRYPTOPP_DLL void CRYPTOPP_API xorbuf(byte *buf, const byte *mask, size_t count); -//! Performs an XOR of an input buffer with a mask and stores the result in an output buffer -//! \param output the destination buffer -//! \param input the source buffer to XOR with the mask -//! \param mask the mask buffer to XOR with the input buffer -//! \param count the size of the buffers, in bytes -//! \details The function effectively visits each element in the buffers and performs -//! output[i] = input[i] ^ mask[i]. output, input and mask must be of equal size. +/// Performs an XOR of an input buffer with a mask and stores the result in an output buffer +/// \param output the destination buffer +/// \param input the source buffer to XOR with the mask +/// \param mask the mask buffer to XOR with the input buffer +/// \param count the size of the buffers, in bytes +/// \details The function effectively visits each element in the buffers and performs +/// output[i] = input[i] ^ mask[i]. output, input and mask must be of equal size. CRYPTOPP_DLL void CRYPTOPP_API xorbuf(byte *output, const byte *input, const byte *mask, size_t count); -//! \brief Performs a near constant-time comparison of two equally sized buffers -//! \param buf1 the first buffer -//! \param buf2 the second buffer -//! \param count the size of the buffers, in bytes -//! \details The function effectively performs an XOR of the elements in two equally sized buffers -//! and retruns a result based on the XOR operation. The function is near constant-time because -//! CPU micro-code timings could affect the "constant-ness". Calling code is responsible for -//! mitigating timing attacks if the buffers are \a not equally sized. -//! \sa ModPowerOf2 +/// \brief Performs a near constant-time comparison of two equally sized buffers +/// \param buf1 the first buffer +/// \param buf2 the second buffer +/// \param count the size of the buffers, in bytes +/// \details The function effectively performs an XOR of the elements in two equally sized buffers +/// and retruns a result based on the XOR operation. The function is near constant-time because +/// CPU micro-code timings could affect the "constant-ness". Calling code is responsible for +/// mitigating timing attacks if the buffers are \a not equally sized. +/// \sa ModPowerOf2 CRYPTOPP_DLL bool CRYPTOPP_API VerifyBufsEqual(const byte *buf1, const byte *buf2, size_t count); -//! \brief Tests whether a value is a power of 2 -//! \param value the value to test -//! \returns true if value is a power of 2, false otherwise -//! \details The function creates a mask of value - 1 and returns the result of -//! an AND operation compared to 0. If value is 0 or less than 0, then the function returns false. +/// \brief Tests whether a value is a power of 2 +/// \param value the value to test +/// \returns true if value is a power of 2, false otherwise +/// \details The function creates a mask of value - 1 and returns the result of +/// an AND operation compared to 0. If value is 0 or less than 0, then the function returns false. template inline bool IsPowerOf2(const T &value) { @@ -868,15 +868,15 @@ inline bool IsPowerOf2(const word64 &value) # endif // __x86_64__ #endif // __BMI__ -//! \brief Performs a saturating subtract clamped at 0 -//! \tparam T1 class or type -//! \tparam T2 class or type -//! \param a the minuend -//! \param b the subtrahend -//! \returns the difference produced by the saturating subtract -//! \details Saturating arithmetic restricts results to a fixed range. Results that are less than 0 are clamped at 0. -//! \details Use of saturating arithmetic in places can be advantageous because it can -//! avoid a branch by using an instruction like a conditional move (CMOVE). +/// \brief Performs a saturating subtract clamped at 0 +/// \tparam T1 class or type +/// \tparam T2 class or type +/// \param a the minuend +/// \param b the subtrahend +/// \returns the difference produced by the saturating subtract +/// \details Saturating arithmetic restricts results to a fixed range. Results that are less than 0 are clamped at 0. +/// \details Use of saturating arithmetic in places can be advantageous because it can +/// avoid a branch by using an instruction like a conditional move (CMOVE). template inline T1 SaturatingSubtract(const T1 &a, const T2 &b) { @@ -884,16 +884,16 @@ inline T1 SaturatingSubtract(const T1 &a, const T2 &b) return T1((a > b) ? (a - b) : 0); } -//! \brief Performs a saturating subtract clamped at 1 -//! \tparam T1 class or type -//! \tparam T2 class or type -//! \param a the minuend -//! \param b the subtrahend -//! \returns the difference produced by the saturating subtract -//! \details Saturating arithmetic restricts results to a fixed range. Results that are less than -//! 1 are clamped at 1. -//! \details Use of saturating arithmetic in places can be advantageous because it can -//! avoid a branch by using an instruction like a conditional move (CMOVE). +/// \brief Performs a saturating subtract clamped at 1 +/// \tparam T1 class or type +/// \tparam T2 class or type +/// \param a the minuend +/// \param b the subtrahend +/// \returns the difference produced by the saturating subtract +/// \details Saturating arithmetic restricts results to a fixed range. Results that are less than +/// 1 are clamped at 1. +/// \details Use of saturating arithmetic in places can be advantageous because it can +/// avoid a branch by using an instruction like a conditional move (CMOVE). template inline T1 SaturatingSubtract1(const T1 &a, const T2 &b) { @@ -901,14 +901,14 @@ inline T1 SaturatingSubtract1(const T1 &a, const T2 &b) return T1((a > b) ? (a - b) : 1); } -//! \brief Reduces a value to a power of 2 -//! \tparam T1 class or type -//! \tparam T2 class or type -//! \param a the first value -//! \param b the second value -//! \returns ModPowerOf2() returns a & (b-1). b must be a power of 2. -//! Use IsPowerOf2() to determine if b is a suitable candidate. -//! \sa IsPowerOf2 +/// \brief Reduces a value to a power of 2 +/// \tparam T1 class or type +/// \tparam T2 class or type +/// \param a the first value +/// \param b the second value +/// \returns ModPowerOf2() returns a & (b-1). b must be a power of 2. +/// Use IsPowerOf2() to determine if b is a suitable candidate. +/// \sa IsPowerOf2 template inline T2 ModPowerOf2(const T1 &a, const T2 &b) { @@ -917,17 +917,17 @@ inline T2 ModPowerOf2(const T1 &a, const T2 &b) return T2(a) & SaturatingSubtract(b,1U); } -//! \brief Rounds a value down to a multiple of a second value -//! \tparam T1 class or type -//! \tparam T2 class or type -//! \param n the value to reduce -//! \param m the value to reduce \n to to a multiple -//! \returns the possibly unmodified value \n -//! \details RoundDownToMultipleOf is effectively a floor function based on m. The function returns -//! the value n - n\%m. If n is a multiple of m, then the original value is returned. -//! \note T1 and T2 should be usigned arithmetic types. If T1 or -//! T2 is signed, then the value should be non-negative. The library asserts in -//! debug builds when practical, but allows you to perform the operation in release builds. +/// \brief Rounds a value down to a multiple of a second value +/// \tparam T1 class or type +/// \tparam T2 class or type +/// \param n the value to reduce +/// \param m the value to reduce \n to to a multiple +/// \returns the possibly unmodified value \n +/// \details RoundDownToMultipleOf is effectively a floor function based on m. The function returns +/// the value n - n\%m. If n is a multiple of m, then the original value is returned. +/// \note T1 and T2 should be usigned arithmetic types. If T1 or +/// T2 is signed, then the value should be non-negative. The library asserts in +/// debug builds when practical, but allows you to perform the operation in release builds. template inline T1 RoundDownToMultipleOf(const T1 &n, const T2 &m) { @@ -946,18 +946,18 @@ inline T1 RoundDownToMultipleOf(const T1 &n, const T2 &m) return n - n%m; } -//! \brief Rounds a value up to a multiple of a second value -//! \tparam T1 class or type -//! \tparam T2 class or type -//! \param n the value to reduce -//! \param m the value to reduce \n to to a multiple -//! \returns the possibly unmodified value \n -//! \details RoundUpToMultipleOf is effectively a ceiling function based on m. The function -//! returns the value n + n\%m. If n is a multiple of m, then the original value is -//! returned. If the value n would overflow, then an InvalidArgument exception is thrown. -//! \note T1 and T2 should be usigned arithmetic types. If T1 or -//! T2 is signed, then the value should be non-negative. The library asserts in -//! debug builds when practical, but allows you to perform the operation in release builds. +/// \brief Rounds a value up to a multiple of a second value +/// \tparam T1 class or type +/// \tparam T2 class or type +/// \param n the value to reduce +/// \param m the value to reduce \n to to a multiple +/// \returns the possibly unmodified value \n +/// \details RoundUpToMultipleOf is effectively a ceiling function based on m. The function +/// returns the value n + n\%m. If n is a multiple of m, then the original value is +/// returned. If the value n would overflow, then an InvalidArgument exception is thrown. +/// \note T1 and T2 should be usigned arithmetic types. If T1 or +/// T2 is signed, then the value should be non-negative. The library asserts in +/// debug builds when practical, but allows you to perform the operation in release builds. template inline T1 RoundUpToMultipleOf(const T1 &n, const T2 &m) { @@ -975,16 +975,16 @@ inline T1 RoundUpToMultipleOf(const T1 &n, const T2 &m) return RoundDownToMultipleOf(T1(n+m-1), m); } -//! \brief Returns the minimum alignment requirements of a type -//! \tparam T class or type -//! \returns the minimum alignment requirements of T, in bytes -//! \details Internally the function calls C++11's alignof if available. If not available, -//! then the function uses compiler specific extensions such as __alignof and -//! _alignof_. If an extension is not available, then the function uses -//! __BIGGEST_ALIGNMENT__ if __BIGGEST_ALIGNMENT__ is smaller than sizeof(T). -//! sizeof(T) is used if all others are not available. -//! In all cases, if CRYPTOPP_ALLOW_UNALIGNED_DATA_ACCESS is defined, then the -//! function returns 1. +/// \brief Returns the minimum alignment requirements of a type +/// \tparam T class or type +/// \returns the minimum alignment requirements of T, in bytes +/// \details Internally the function calls C++11's alignof if available. If not available, +/// then the function uses compiler specific extensions such as __alignof and +/// _alignof_. If an extension is not available, then the function uses +/// __BIGGEST_ALIGNMENT__ if __BIGGEST_ALIGNMENT__ is smaller than sizeof(T). +/// sizeof(T) is used if all others are not available. +/// In all cases, if CRYPTOPP_ALLOW_UNALIGNED_DATA_ACCESS is defined, then the +/// function returns 1. template inline unsigned int GetAlignmentOf() { @@ -1012,22 +1012,22 @@ inline unsigned int GetAlignmentOf() #endif } -//! \brief Determines whether ptr is aligned to a minimum value -//! \param ptr the pointer being checked for alignment -//! \param alignment the alignment value to test the pointer against -//! \returns true if ptr is aligned on at least alignment boundary, false otherwise -//! \details Internally the function tests whether alignment is 1. If so, the function returns true. -//! If not, then the function effectively performs a modular reduction and returns true if the residue is 0 +/// \brief Determines whether ptr is aligned to a minimum value +/// \param ptr the pointer being checked for alignment +/// \param alignment the alignment value to test the pointer against +/// \returns true if ptr is aligned on at least alignment boundary, false otherwise +/// \details Internally the function tests whether alignment is 1. If so, the function returns true. +/// If not, then the function effectively performs a modular reduction and returns true if the residue is 0 inline bool IsAlignedOn(const void *ptr, unsigned int alignment) { return alignment==1 || (IsPowerOf2(alignment) ? ModPowerOf2((size_t)ptr, alignment) == 0 : (size_t)ptr % alignment == 0); } -//! \brief Determines whether ptr is minimally aligned -//! \tparam T class or type -//! \param ptr the pointer to check for alignment -//! \returns true if ptr is aligned to at least T boundary, false otherwise -//! \details Internally the function calls IsAlignedOn with a second parameter of GetAlignmentOf +/// \brief Determines whether ptr is minimally aligned +/// \tparam T class or type +/// \param ptr the pointer to check for alignment +/// \returns true if ptr is aligned to at least T boundary, false otherwise +/// \details Internally the function calls IsAlignedOn with a second parameter of GetAlignmentOf template inline bool IsAligned(const void *ptr) { @@ -1042,60 +1042,60 @@ inline bool IsAligned(const void *ptr) # error "Unable to determine endian-ness" #endif -//! \brief Returns NativeByteOrder as an enumerated ByteOrder value -//! \returns LittleEndian if the native byte order is little-endian, and BigEndian if the -//! native byte order is big-endian -//! \details NativeByteOrder is a typedef depending on the platform. If CRYPTOPP_LITTLE_ENDIAN is -//! set in config.h, then GetNativeByteOrder returns LittleEndian. If -//! CRYPTOPP_BIG_ENDIAN is set, then GetNativeByteOrder returns BigEndian. -//! \note There are other byte orders besides little- and big-endian, and they include bi-endian -//! and PDP-endian. If a system is neither little-endian nor big-endian, then a compile time -//! error occurs. +/// \brief Returns NativeByteOrder as an enumerated ByteOrder value +/// \returns LittleEndian if the native byte order is little-endian, and BigEndian if the +/// native byte order is big-endian +/// \details NativeByteOrder is a typedef depending on the platform. If CRYPTOPP_LITTLE_ENDIAN is +/// set in config.h, then GetNativeByteOrder returns LittleEndian. If +/// CRYPTOPP_BIG_ENDIAN is set, then GetNativeByteOrder returns BigEndian. +/// \note There are other byte orders besides little- and big-endian, and they include bi-endian +/// and PDP-endian. If a system is neither little-endian nor big-endian, then a compile time +/// error occurs. inline ByteOrder GetNativeByteOrder() { return NativeByteOrder::ToEnum(); } -//! \brief Determines whether order follows native byte ordering -//! \param order the ordering being tested against native byte ordering -//! \returns true if order follows native byte ordering, false otherwise +/// \brief Determines whether order follows native byte ordering +/// \param order the ordering being tested against native byte ordering +/// \returns true if order follows native byte ordering, false otherwise inline bool NativeByteOrderIs(ByteOrder order) { return order == GetNativeByteOrder(); } -//! \brief Returns the direction the cipher is being operated -//! \tparam T class or type -//! \param obj the cipher object being queried -//! \returns \p ENCRYPTION if the cipher obj is being operated in its forward direction, -//! \p DECRYPTION otherwise -//! \details A cipher can be operated in a "forward" direction (encryption) or a "reverse" -//! direction (decryption). The operations do not have to be symmetric, meaning a second -//! application of the transformation does not necessariy return the original message. -//! That is, E(D(m)) may not equal E(E(m)); and D(E(m)) may not -//! equal D(D(m)). +/// \brief Returns the direction the cipher is being operated +/// \tparam T class or type +/// \param obj the cipher object being queried +/// \returns \p ENCRYPTION if the cipher obj is being operated in its forward direction, +/// \p DECRYPTION otherwise +/// \details A cipher can be operated in a "forward" direction (encryption) or a "reverse" +/// direction (decryption). The operations do not have to be symmetric, meaning a second +/// application of the transformation does not necessariy return the original message. +/// That is, E(D(m)) may not equal E(E(m)); and D(E(m)) may not +/// equal D(D(m)). template inline CipherDir GetCipherDir(const T &obj) { return obj.IsForwardTransformation() ? ENCRYPTION : DECRYPTION; } -//! \brief Attempts to reclaim unused memory -//! \throws bad_alloc -//! \details In the normal course of running a program, a request for memory normally succeeds. If a -//! call to AlignedAllocate or UnalignedAllocate fails, then CallNewHandler is called in -//! an effort to recover. Internally, CallNewHandler calls set_new_handler(NULLPTR) in an effort -//! to free memory. There is no guarantee CallNewHandler will be able to procure more memory so -//! an allocation succeeds. If the call to set_new_handler fails, then CallNewHandler throws -//! a bad_alloc exception. +/// \brief Attempts to reclaim unused memory +/// \throws bad_alloc +/// \details In the normal course of running a program, a request for memory normally succeeds. If a +/// call to AlignedAllocate or UnalignedAllocate fails, then CallNewHandler is called in +/// an effort to recover. Internally, CallNewHandler calls set_new_handler(NULLPTR) in an effort +/// to free memory. There is no guarantee CallNewHandler will be able to procure more memory so +/// an allocation succeeds. If the call to set_new_handler fails, then CallNewHandler throws +/// a bad_alloc exception. CRYPTOPP_DLL void CRYPTOPP_API CallNewHandler(); -//! \brief Performs an addition with carry on a block of bytes -//! \param inout the byte block -//! \param size the size of the block, in bytes -//! \details Performs an addition with carry by adding 1 on a block of bytes starting at the least -//! significant byte. Once carry is 0, the function terminates and returns to the caller. -//! \note The function is not constant time because it stops processing when the carry is 0. +/// \brief Performs an addition with carry on a block of bytes +/// \param inout the byte block +/// \param size the size of the block, in bytes +/// \details Performs an addition with carry by adding 1 on a block of bytes starting at the least +/// significant byte. Once carry is 0, the function terminates and returns to the caller. +/// \note The function is not constant time because it stops processing when the carry is 0. inline void IncrementCounterByOne(byte *inout, unsigned int size) { CRYPTOPP_ASSERT(inout != NULLPTR); CRYPTOPP_ASSERT(size < INT_MAX); @@ -1103,13 +1103,13 @@ inline void IncrementCounterByOne(byte *inout, unsigned int size) carry = !++inout[i]; } -//! \brief Performs an addition with carry on a block of bytes -//! \param output the destination block of bytes -//! \param input the source block of bytes -//! \param size the size of the block -//! \details Performs an addition with carry on a block of bytes starting at the least significant -//! byte. Once carry is 0, the remaining bytes from input are copied to output using memcpy. -//! \details The function is \a close to near-constant time because it operates on all the bytes in the blocks. +/// \brief Performs an addition with carry on a block of bytes +/// \param output the destination block of bytes +/// \param input the source block of bytes +/// \param size the size of the block +/// \details Performs an addition with carry on a block of bytes starting at the least significant +/// byte. Once carry is 0, the remaining bytes from input are copied to output using memcpy. +/// \details The function is \a close to near-constant time because it operates on all the bytes in the blocks. inline void IncrementCounterByOne(byte *output, const byte *input, unsigned int size) { CRYPTOPP_ASSERT(output != NULLPTR); CRYPTOPP_ASSERT(input != NULLPTR); CRYPTOPP_ASSERT(size < INT_MAX); @@ -1120,11 +1120,11 @@ inline void IncrementCounterByOne(byte *output, const byte *input, unsigned int memcpy_s(output, size, input, size_t(i)+1); } -//! \brief Performs a branchless swap of values a and b if condition c is true -//! \tparam T class or type -//! \param c the condition to perform the swap -//! \param a the first value -//! \param b the second value +/// \brief Performs a branchless swap of values a and b if condition c is true +/// \tparam T class or type +/// \param c the condition to perform the swap +/// \param a the first value +/// \param b the second value template inline void ConditionalSwap(bool c, T &a, T &b) { @@ -1133,11 +1133,11 @@ inline void ConditionalSwap(bool c, T &a, T &b) b ^= t; } -//! \brief Performs a branchless swap of pointers a and b if condition c is true -//! \tparam T class or type -//! \param c the condition to perform the swap -//! \param a the first pointer -//! \param b the second pointer +/// \brief Performs a branchless swap of pointers a and b if condition c is true +/// \tparam T class or type +/// \param c the condition to perform the swap +/// \param a the first pointer +/// \param b the second pointer template inline void ConditionalSwapPointers(bool c, T &a, T &b) { @@ -1149,11 +1149,11 @@ inline void ConditionalSwapPointers(bool c, T &a, T &b) // see http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html // and http://www.securecoding.cert.org/confluence/display/cplusplus/MSC06-CPP.+Be+aware+of+compiler+optimization+when+dealing+with+sensitive+data -//! \brief Sets each element of an array to 0 -//! \tparam T class or type -//! \param buf an array of elements -//! \param n the number of elements in the array -//! \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal +/// \brief Sets each element of an array to 0 +/// \tparam T class or type +/// \param buf an array of elements +/// \param n the number of elements in the array +/// \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal template void SecureWipeBuffer(T *buf, size_t n) { @@ -1165,10 +1165,10 @@ void SecureWipeBuffer(T *buf, size_t n) #if (_MSC_VER >= 1400 || defined(__GNUC__)) && (CRYPTOPP_BOOL_X64 || CRYPTOPP_BOOL_X86) -//! \brief Sets each byte of an array to 0 -//! \param buf an array of bytes -//! \param n the number of elements in the array -//! \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. +/// \brief Sets each byte of an array to 0 +/// \param buf an array of bytes +/// \param n the number of elements in the array +/// \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. template<> inline void SecureWipeBuffer(byte *buf, size_t n) { volatile byte *p = buf; @@ -1179,10 +1179,10 @@ template<> inline void SecureWipeBuffer(byte *buf, size_t n) #endif } -//! \brief Sets each 16-bit element of an array to 0 -//! \param buf an array of 16-bit words -//! \param n the number of elements in the array -//! \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. +/// \brief Sets each 16-bit element of an array to 0 +/// \param buf an array of 16-bit words +/// \param n the number of elements in the array +/// \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. template<> inline void SecureWipeBuffer(word16 *buf, size_t n) { volatile word16 *p = buf; @@ -1193,10 +1193,10 @@ template<> inline void SecureWipeBuffer(word16 *buf, size_t n) #endif } -//! \brief Sets each 32-bit element of an array to 0 -//! \param buf an array of 32-bit words -//! \param n the number of elements in the array -//! \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. +/// \brief Sets each 32-bit element of an array to 0 +/// \param buf an array of 32-bit words +/// \param n the number of elements in the array +/// \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. template<> inline void SecureWipeBuffer(word32 *buf, size_t n) { volatile word32 *p = buf; @@ -1207,10 +1207,10 @@ template<> inline void SecureWipeBuffer(word32 *buf, size_t n) #endif } -//! \brief Sets each 64-bit element of an array to 0 -//! \param buf an array of 64-bit words -//! \param n the number of elements in the array -//! \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. +/// \brief Sets each 64-bit element of an array to 0 +/// \param buf an array of 64-bit words +/// \param n the number of elements in the array +/// \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. template<> inline void SecureWipeBuffer(word64 *buf, size_t n) { #if CRYPTOPP_BOOL_X64 @@ -1257,11 +1257,11 @@ template<> inline void SecureWipeBuffer(word64 *buf, size_t n) } #endif -//! \brief Sets each element of an array to 0 -//! \tparam T class or type -//! \param buf an array of elements -//! \param n the number of elements in the array -//! \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. +/// \brief Sets each element of an array to 0 +/// \tparam T class or type +/// \param buf an array of elements +/// \param n the number of elements in the array +/// \details The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal. template inline void SecureWipeArray(T *buf, size_t n) { @@ -1275,50 +1275,50 @@ inline void SecureWipeArray(T *buf, size_t n) SecureWipeBuffer((byte *)(void *)buf, n * sizeof(T)); } -//! \brief Converts a wide character C-string to a multibyte string -//! \param str C-string consisting of wide characters -//! \param throwOnError flag indicating the function should throw on error -//! \returns str converted to a multibyte string or an empty string. -//! \details StringNarrow() converts a wide string to a narrow string using C++ std::wcstombs() under -//! the executing thread's locale. A locale must be set before using this function, and it can be -//! set with std::setlocale() if needed. Upon success, the converted string is returned. -//! \details Upon failure with throwOnError as false, the function returns an empty string. If -//! throwOnError as true, the function throws an InvalidArgument() exception. -//! \note If you try to convert, say, the Chinese character for "bone" from UTF-16 (0x9AA8) to UTF-8 -//! (0xE9 0xAA 0xA8), then you must ensure the locale is available. If the locale is not available, -//! then a 0x21 error is returned on Windows which eventually results in an InvalidArgument() exception. +/// \brief Converts a wide character C-string to a multibyte string +/// \param str C-string consisting of wide characters +/// \param throwOnError flag indicating the function should throw on error +/// \returns str converted to a multibyte string or an empty string. +/// \details StringNarrow() converts a wide string to a narrow string using C++ std::wcstombs() under +/// the executing thread's locale. A locale must be set before using this function, and it can be +/// set with std::setlocale() if needed. Upon success, the converted string is returned. +/// \details Upon failure with throwOnError as false, the function returns an empty string. If +/// throwOnError as true, the function throws an InvalidArgument() exception. +/// \note If you try to convert, say, the Chinese character for "bone" from UTF-16 (0x9AA8) to UTF-8 +/// (0xE9 0xAA 0xA8), then you must ensure the locale is available. If the locale is not available, +/// then a 0x21 error is returned on Windows which eventually results in an InvalidArgument() exception. std::string StringNarrow(const wchar_t *str, bool throwOnError = true); -//! \brief Converts a multibyte C-string to a wide character string -//! \param str C-string consisting of wide characters -//! \param throwOnError flag indicating the function should throw on error -//! \returns str converted to a multibyte string or an empty string. -//! \details StringWiden() converts a narrow string to a wide string using C++ std::mbstowcs() under -//! the executing thread's locale. A locale must be set before using this function, and it can be -//! set with std::setlocale() if needed. Upon success, the converted string is returned. -//! \details Upon failure with throwOnError as false, the function returns an empty string. If -//! throwOnError as true, the function throws an InvalidArgument() exception. -//! \note If you try to convert, say, the Chinese character for "bone" from UTF-8 (0xE9 0xAA 0xA8) -//! to UTF-16 (0x9AA8), then you must ensure the locale is available. If the locale is not available, -//! then a 0x21 error is returned on Windows which eventually results in an InvalidArgument() exception. +/// \brief Converts a multibyte C-string to a wide character string +/// \param str C-string consisting of wide characters +/// \param throwOnError flag indicating the function should throw on error +/// \returns str converted to a multibyte string or an empty string. +/// \details StringWiden() converts a narrow string to a wide string using C++ std::mbstowcs() under +/// the executing thread's locale. A locale must be set before using this function, and it can be +/// set with std::setlocale() if needed. Upon success, the converted string is returned. +/// \details Upon failure with throwOnError as false, the function returns an empty string. If +/// throwOnError as true, the function throws an InvalidArgument() exception. +/// \note If you try to convert, say, the Chinese character for "bone" from UTF-8 (0xE9 0xAA 0xA8) +/// to UTF-16 (0x9AA8), then you must ensure the locale is available. If the locale is not available, +/// then a 0x21 error is returned on Windows which eventually results in an InvalidArgument() exception. std::wstring StringWiden(const char *str, bool throwOnError = true); #ifdef CRYPTOPP_DOXYGEN_PROCESSING -//! \brief Allocates a buffer on 16-byte boundary -//! \param size the size of the buffer -//! \details AlignedAllocate is primarily used when the data will be proccessed by MMX, SSE2 and NEON -//! instructions. The assembly language routines rely on the alignment. If the alignment is not -//! respected, then a SIGBUS could be generated on Unix and Linux, and an -//! EXCEPTION_DATATYPE_MISALIGNMENT could be generated on Windows. -//! \note AlignedAllocate and AlignedDeallocate are available when CRYPTOPP_BOOL_ALIGN16 is -//! defined. CRYPTOPP_BOOL_ALIGN16 is defined in config.h +/// \brief Allocates a buffer on 16-byte boundary +/// \param size the size of the buffer +/// \details AlignedAllocate is primarily used when the data will be proccessed by MMX, SSE2 and NEON +/// instructions. The assembly language routines rely on the alignment. If the alignment is not +/// respected, then a SIGBUS could be generated on Unix and Linux, and an +/// EXCEPTION_DATATYPE_MISALIGNMENT could be generated on Windows. +/// \note AlignedAllocate and AlignedDeallocate are available when CRYPTOPP_BOOL_ALIGN16 is +/// defined. CRYPTOPP_BOOL_ALIGN16 is defined in config.h CRYPTOPP_DLL void* CRYPTOPP_API AlignedAllocate(size_t size); -//! \brief Frees a buffer allocated with AlignedAllocate -//! \param ptr the buffer to free -//! \note AlignedAllocate and AlignedDeallocate are available when CRYPTOPP_BOOL_ALIGN16 is -//! defined. CRYPTOPP_BOOL_ALIGN16 is defined in config.h +/// \brief Frees a buffer allocated with AlignedAllocate +/// \param ptr the buffer to free +/// \note AlignedAllocate and AlignedDeallocate are available when CRYPTOPP_BOOL_ALIGN16 is +/// defined. CRYPTOPP_BOOL_ALIGN16 is defined in config.h CRYPTOPP_DLL void CRYPTOPP_API AlignedDeallocate(void *ptr); #endif // CRYPTOPP_DOXYGEN_PROCESSING @@ -1328,31 +1328,31 @@ CRYPTOPP_DLL void* CRYPTOPP_API AlignedAllocate(size_t size); CRYPTOPP_DLL void CRYPTOPP_API AlignedDeallocate(void *ptr); #endif // CRYPTOPP_BOOL_ALIGN16 -//! \brief Allocates a buffer -//! \param size the size of the buffer +/// \brief Allocates a buffer +/// \param size the size of the buffer CRYPTOPP_DLL void * CRYPTOPP_API UnalignedAllocate(size_t size); -//! \brief Frees a buffer allocated with UnalignedAllocate -//! \param ptr the buffer to free +/// \brief Frees a buffer allocated with UnalignedAllocate +/// \param ptr the buffer to free CRYPTOPP_DLL void CRYPTOPP_API UnalignedDeallocate(void *ptr); // ************** rotate functions *************** -//! \brief Performs a left rotate -//! \tparam R the number of bit positions to rotate the value -//! \tparam T the word type -//! \param x the value to rotate -//! \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. -//! \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! Use rotlMod if the rotate amount y is outside the range. -//! \details Use rotlConstant when the rotate amount is constant. The template function was added -//! because Clang did not propagate the constant when passed as a function parameter. Clang's -//! need for a constexpr meant rotlFixed failed to compile on occassion. -//! \note rotlConstant attempts to enlist a rotate IMM instruction because its often faster -//! than a rotate REG. Immediate rotates can be up to three times faster than their register -//! counterparts. -//! \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable -//! \since Crypto++ 6.0 +/// \brief Performs a left rotate +/// \tparam R the number of bit positions to rotate the value +/// \tparam T the word type +/// \param x the value to rotate +/// \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. +/// \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// Use rotlMod if the rotate amount y is outside the range. +/// \details Use rotlConstant when the rotate amount is constant. The template function was added +/// because Clang did not propagate the constant when passed as a function parameter. Clang's +/// need for a constexpr meant rotlFixed failed to compile on occassion. +/// \note rotlConstant attempts to enlist a rotate IMM instruction because its often faster +/// than a rotate REG. Immediate rotates can be up to three times faster than their register +/// counterparts. +/// \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable +/// \since Crypto++ 6.0 template inline T rotlConstant(T x) { // Portable rotate that reduces to single instruction... @@ -1365,20 +1365,20 @@ template inline T rotlConstant(T x) return T((x<>(-R&MASK))); } -//! \brief Performs a right rotate -//! \tparam R the number of bit positions to rotate the value -//! \tparam T the word type -//! \param x the value to rotate -//! \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. -//! \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! Use rotrMod if the rotate amount y is outside the range. -//! \details Use rotrConstant when the rotate amount is constant. The template function was added -//! because Clang did not propagate the constant when passed as a function parameter. Clang's -//! need for a constexpr meant rotrFixed failed to compile on occassion. -//! \note rotrConstant attempts to enlist a rotate IMM instruction because its often faster -//! than a rotate REG. Immediate rotates can be up to three times faster than their register -//! counterparts. -//! \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable +/// \brief Performs a right rotate +/// \tparam R the number of bit positions to rotate the value +/// \tparam T the word type +/// \param x the value to rotate +/// \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. +/// \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// Use rotrMod if the rotate amount y is outside the range. +/// \details Use rotrConstant when the rotate amount is constant. The template function was added +/// because Clang did not propagate the constant when passed as a function parameter. Clang's +/// need for a constexpr meant rotrFixed failed to compile on occassion. +/// \note rotrConstant attempts to enlist a rotate IMM instruction because its often faster +/// than a rotate REG. Immediate rotates can be up to three times faster than their register +/// counterparts. +/// \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable template inline T rotrConstant(T x) { // Portable rotate that reduces to single instruction... @@ -1391,18 +1391,18 @@ template inline T rotrConstant(T x) return T((x >> R)|(x<<(-R&MASK))); } -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. -//! \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! Use rotlMod if the rotate amount y is outside the range. -//! \note rotlFixed attempts to enlist a rotate IMM instruction because its often faster -//! than a rotate REG. Immediate rotates can be up to three times faster than their register -//! counterparts. -//! \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable -//! \since Crypto++ 6.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. +/// \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// Use rotlMod if the rotate amount y is outside the range. +/// \note rotlFixed attempts to enlist a rotate IMM instruction because its often faster +/// than a rotate REG. Immediate rotates can be up to three times faster than their register +/// counterparts. +/// \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable +/// \since Crypto++ 6.0 template inline T rotlFixed(T x, unsigned int y) { // Portable rotate that reduces to single instruction... @@ -1415,18 +1415,18 @@ template inline T rotlFixed(T x, unsigned int y) return T((x<>(-y&MASK))); } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. -//! \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! Use rotrMod if the rotate amount y is outside the range. -//! \note rotrFixed attempts to enlist a rotate IMM instruction because its often faster -//! than a rotate REG. Immediate rotates can be up to three times faster than their register -//! counterparts. -//! \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. +/// \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// Use rotrMod if the rotate amount y is outside the range. +/// \note rotrFixed attempts to enlist a rotate IMM instruction because its often faster +/// than a rotate REG. Immediate rotates can be up to three times faster than their register +/// counterparts. +/// \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable +/// \since Crypto++ 3.0 template inline T rotrFixed(T x, unsigned int y) { // Portable rotate that reduces to single instruction... @@ -1439,18 +1439,18 @@ template inline T rotrFixed(T x, unsigned int y) return T((x >> y)|(x<<(-y&MASK))); } -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. -//! \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! Use rotlMod if the rotate amount y is outside the range. -//! \note rotlVariable attempts to enlist a rotate IMM instruction because its often faster -//! than a rotate REG. Immediate rotates can be up to three times faster than their register -//! counterparts. -//! \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable -//! \since Crypto++ 3.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. +/// \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// Use rotlMod if the rotate amount y is outside the range. +/// \note rotlVariable attempts to enlist a rotate IMM instruction because its often faster +/// than a rotate REG. Immediate rotates can be up to three times faster than their register +/// counterparts. +/// \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable +/// \since Crypto++ 3.0 template inline T rotlVariable(T x, unsigned int y) { static const unsigned int THIS_SIZE = sizeof(T)*8; @@ -1459,18 +1459,18 @@ template inline T rotlVariable(T x, unsigned int y) return T((x<>(-y&MASK))); } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. -//! \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! Use rotrMod if the rotate amount y is outside the range. -//! \note rotrVariable attempts to enlist a rotate IMM instruction because its often faster -//! than a rotate REG. Immediate rotates can be up to three times faster than their register -//! counterparts. -//! \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. +/// \details y must be in the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// Use rotrMod if the rotate amount y is outside the range. +/// \note rotrVariable attempts to enlist a rotate IMM instruction because its often faster +/// than a rotate REG. Immediate rotates can be up to three times faster than their register +/// counterparts. +/// \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable +/// \since Crypto++ 3.0 template inline T rotrVariable(T x, unsigned int y) { static const unsigned int THIS_SIZE = sizeof(T)*8; @@ -1479,15 +1479,15 @@ template inline T rotrVariable(T x, unsigned int y) return T((x>>y)|(x<<(-y&MASK))); } -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. -//! \details y is reduced to the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotrVariable will use either rotate IMM or rotate REG. -//! \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable -//! \since Crypto++ 3.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. +/// \details y is reduced to the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotrVariable will use either rotate IMM or rotate REG. +/// \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable +/// \since Crypto++ 3.0 template inline T rotlMod(T x, unsigned int y) { static const unsigned int THIS_SIZE = sizeof(T)*8; @@ -1495,15 +1495,15 @@ template inline T rotlMod(T x, unsigned int y) return T((x<<(y&MASK))|(x>>(-y&MASK))); } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. -//! \details y is reduced to the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotrVariable will use either rotate IMM or rotate REG. -//! \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide. +/// \details y is reduced to the range [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotrVariable will use either rotate IMM or rotate REG. +/// \sa rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable +/// \since Crypto++ 3.0 template inline T rotrMod(T x, unsigned int y) { static const unsigned int THIS_SIZE = sizeof(T)*8; @@ -1513,15 +1513,15 @@ template inline T rotrMod(T x, unsigned int y) #ifdef _MSC_VER -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the 32-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotl provided by -//! . The value x to be rotated is 32-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotlFixed will assert in Debug builds if is outside the allowed range. -//! \since Crypto++ 3.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the 32-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotl provided by +/// . The value x to be rotated is 32-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotlFixed will assert in Debug builds if is outside the allowed range. +/// \since Crypto++ 3.0 template<> inline word32 rotlFixed(word32 x, unsigned int y) { // Uses Microsoft call, bound to C/C++ language rules. @@ -1529,15 +1529,15 @@ template<> inline word32 rotlFixed(word32 x, unsigned int y) return y ? _lrotl(x, static_cast(y)) : x; } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the 32-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotr provided by -//! . The value x to be rotated is 32-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotrFixed will assert in Debug builds if is outside the allowed range. -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the 32-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotr provided by +/// . The value x to be rotated is 32-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotrFixed will assert in Debug builds if is outside the allowed range. +/// \since Crypto++ 3.0 template<> inline word32 rotrFixed(word32 x, unsigned int y) { // Uses Microsoft call, bound to C/C++ language rules. @@ -1545,58 +1545,58 @@ template<> inline word32 rotrFixed(word32 x, unsigned int y) return y ? _lrotr(x, static_cast(y)) : x; } -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the 32-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotl provided by -//! . The value x to be rotated is 32-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotlVariable will assert in Debug builds if is outside the allowed range. -//! \since Crypto++ 3.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the 32-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotl provided by +/// . The value x to be rotated is 32-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotlVariable will assert in Debug builds if is outside the allowed range. +/// \since Crypto++ 3.0 template<> inline word32 rotlVariable(word32 x, unsigned int y) { CRYPTOPP_ASSERT(y < 8*sizeof(x)); return _lrotl(x, static_cast(y)); } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the 32-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotr provided by -//! . The value x to be rotated is 32-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotrVariable will assert in Debug builds if is outside the allowed range. -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the 32-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotr provided by +/// . The value x to be rotated is 32-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotrVariable will assert in Debug builds if is outside the allowed range. +/// \since Crypto++ 3.0 template<> inline word32 rotrVariable(word32 x, unsigned int y) { CRYPTOPP_ASSERT(y < 8*sizeof(x)); return _lrotr(x, static_cast(y)); } -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the 32-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotl provided by -//! . The value x to be rotated is 32-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \since Crypto++ 3.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the 32-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotl provided by +/// . The value x to be rotated is 32-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \since Crypto++ 3.0 template<> inline word32 rotlMod(word32 x, unsigned int y) { y %= 8*sizeof(x); return _lrotl(x, static_cast(y)); } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the 32-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotr provided by -//! . The value x to be rotated is 32-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the 32-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotr provided by +/// . The value x to be rotated is 32-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \since Crypto++ 3.0 template<> inline word32 rotrMod(word32 x, unsigned int y) { y %= 8*sizeof(x); @@ -1608,15 +1608,15 @@ template<> inline word32 rotrMod(word32 x, unsigned int y) #if (_MSC_VER >= 1400) || (defined(_MSC_VER) && !defined(_DLL)) // Intel C++ Compiler 10.0 calls a function instead of using the rotate instruction when using these instructions -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the 64-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotl provided by -//! . The value x to be rotated is 64-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotrFixed will assert in Debug builds if is outside the allowed range. -//! \since Crypto++ 3.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the 64-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotl provided by +/// . The value x to be rotated is 64-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotrFixed will assert in Debug builds if is outside the allowed range. +/// \since Crypto++ 3.0 template<> inline word64 rotlFixed(word64 x, unsigned int y) { // Uses Microsoft call, bound to C/C++ language rules. @@ -1624,15 +1624,15 @@ template<> inline word64 rotlFixed(word64 x, unsigned int y) return y ? _rotl64(x, static_cast(y)) : x; } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the 64-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotr provided by -//! . The value x to be rotated is 64-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotrFixed will assert in Debug builds if is outside the allowed range. -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the 64-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotr provided by +/// . The value x to be rotated is 64-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotrFixed will assert in Debug builds if is outside the allowed range. +/// \since Crypto++ 3.0 template<> inline word64 rotrFixed(word64 x, unsigned int y) { // Uses Microsoft call, bound to C/C++ language rules. @@ -1640,58 +1640,58 @@ template<> inline word64 rotrFixed(word64 x, unsigned int y) return y ? _rotr64(x, static_cast(y)) : x; } -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the 64-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotl provided by -//! . The value x to be rotated is 64-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotlVariable will assert in Debug builds if is outside the allowed range. -//! \since Crypto++ 3.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the 64-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotl provided by +/// . The value x to be rotated is 64-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotlVariable will assert in Debug builds if is outside the allowed range. +/// \since Crypto++ 3.0 template<> inline word64 rotlVariable(word64 x, unsigned int y) { CRYPTOPP_ASSERT(y < 8*sizeof(x)); return _rotl64(x, static_cast(y)); } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the 64-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotr provided by -//! . The value x to be rotated is 64-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \note rotrVariable will assert in Debug builds if is outside the allowed range. -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the 64-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotr provided by +/// . The value x to be rotated is 64-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \note rotrVariable will assert in Debug builds if is outside the allowed range. +/// \since Crypto++ 3.0 template<> inline word64 rotrVariable(word64 x, unsigned int y) { CRYPTOPP_ASSERT(y < 8*sizeof(x)); return y ? _rotr64(x, static_cast(y)) : x; } -//! \brief Performs a left rotate -//! \tparam T the word type -//! \param x the 64-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotl provided by -//! . The value x to be rotated is 64-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \since Crypto++ 3.0 +/// \brief Performs a left rotate +/// \tparam T the word type +/// \param x the 64-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotl provided by +/// . The value x to be rotated is 64-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \since Crypto++ 3.0 template<> inline word64 rotlMod(word64 x, unsigned int y) { CRYPTOPP_ASSERT(y < 8*sizeof(x)); return y ? _rotl64(x, static_cast(y)) : x; } -//! \brief Performs a right rotate -//! \tparam T the word type -//! \param x the 64-bit value to rotate -//! \param y the number of bit positions to rotate the value -//! \details This is a Microsoft specific implementation using _lrotr provided by -//! . The value x to be rotated is 64-bits. y must be in the range -//! [0, sizeof(T)*8 - 1] to avoid undefined behavior. -//! \since Crypto++ 3.0 +/// \brief Performs a right rotate +/// \tparam T the word type +/// \param x the 64-bit value to rotate +/// \param y the number of bit positions to rotate the value +/// \details This is a Microsoft specific implementation using _lrotr provided by +/// . The value x to be rotated is 64-bits. y must be in the range +/// [0, sizeof(T)*8 - 1] to avoid undefined behavior. +/// \since Crypto++ 3.0 template<> inline word64 rotrMod(word64 x, unsigned int y) { CRYPTOPP_ASSERT(y < 8*sizeof(x)); @@ -1808,10 +1808,10 @@ template<> inline word32 rotrMod(word32 x, unsigned int y) // ************** endian reversal *************** -//! \brief Gets a byte from a value -//! \param order the ByteOrder of the value -//! \param value the value to retrieve the byte -//! \param index the location of the byte to retrieve +/// \brief Gets a byte from a value +/// \param order the ByteOrder of the value +/// \param value the value to retrieve the byte +/// \param index the location of the byte to retrieve template inline unsigned int GetByte(ByteOrder order, T value, unsigned int index) { @@ -1821,17 +1821,17 @@ inline unsigned int GetByte(ByteOrder order, T value, unsigned int index) return GETBYTE(value, sizeof(T)-index-1); } -//! \brief Reverses bytes in a 8-bit value -//! \param value the 8-bit value to reverse -//! \note ByteReverse returns the value passed to it since there is nothing to reverse +/// \brief Reverses bytes in a 8-bit value +/// \param value the 8-bit value to reverse +/// \note ByteReverse returns the value passed to it since there is nothing to reverse inline byte ByteReverse(byte value) { return value; } -//! \brief Reverses bytes in a 16-bit value -//! \param value the 16-bit value to reverse -//! \details ByteReverse calls bswap if available. Otherwise the function performs a 8-bit rotate on the word16 +/// \brief Reverses bytes in a 16-bit value +/// \param value the 16-bit value to reverse +/// \details ByteReverse calls bswap if available. Otherwise the function performs a 8-bit rotate on the word16 inline word16 ByteReverse(word16 value) { #if defined(CRYPTOPP_BYTESWAP_AVAILABLE) @@ -1843,9 +1843,9 @@ inline word16 ByteReverse(word16 value) #endif } -//! \brief Reverses bytes in a 32-bit value -//! \param value the 32-bit value to reverse -//! \details ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word32 +/// \brief Reverses bytes in a 32-bit value +/// \param value the 32-bit value to reverse +/// \details ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word32 inline word32 ByteReverse(word32 value) { #if defined(__GNUC__) && defined(CRYPTOPP_X86_ASM_AVAILABLE) @@ -1867,9 +1867,9 @@ inline word32 ByteReverse(word32 value) #endif } -//! \brief Reverses bytes in a 64-bit value -//! \param value the 64-bit value to reverse -//! \details ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word64 +/// \brief Reverses bytes in a 64-bit value +/// \param value the 64-bit value to reverse +/// \details ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word64 inline word64 ByteReverse(word64 value) { #if defined(__GNUC__) && defined(CRYPTOPP_X86_ASM_AVAILABLE) && defined(__x86_64__) @@ -1888,9 +1888,9 @@ inline word64 ByteReverse(word64 value) #endif } -//! \brief Reverses bits in a 8-bit value -//! \param value the 8-bit value to reverse -//! \details BitReverse performs a combination of shifts on the byte +/// \brief Reverses bits in a 8-bit value +/// \param value the 8-bit value to reverse +/// \details BitReverse performs a combination of shifts on the byte inline byte BitReverse(byte value) { value = byte((value & 0xAA) >> 1) | byte((value & 0x55) << 1); @@ -1898,9 +1898,9 @@ inline byte BitReverse(byte value) return rotlFixed(value, 4U); } -//! \brief Reverses bits in a 16-bit value -//! \param value the 16-bit value to reverse -//! \details BitReverse performs a combination of shifts on the word16 +/// \brief Reverses bits in a 16-bit value +/// \param value the 16-bit value to reverse +/// \details BitReverse performs a combination of shifts on the word16 inline word16 BitReverse(word16 value) { value = word16((value & 0xAAAA) >> 1) | word16((value & 0x5555) << 1); @@ -1909,9 +1909,9 @@ inline word16 BitReverse(word16 value) return ByteReverse(value); } -//! \brief Reverses bits in a 32-bit value -//! \param value the 32-bit value to reverse -//! \details BitReverse performs a combination of shifts on the word32 +/// \brief Reverses bits in a 32-bit value +/// \param value the 32-bit value to reverse +/// \details BitReverse performs a combination of shifts on the word32 inline word32 BitReverse(word32 value) { value = word32((value & 0xAAAAAAAA) >> 1) | word32((value & 0x55555555) << 1); @@ -1920,9 +1920,9 @@ inline word32 BitReverse(word32 value) return ByteReverse(value); } -//! \brief Reverses bits in a 64-bit value -//! \param value the 64-bit value to reverse -//! \details BitReverse performs a combination of shifts on the word64 +/// \brief Reverses bits in a 64-bit value +/// \param value the 64-bit value to reverse +/// \details BitReverse performs a combination of shifts on the word64 inline word64 BitReverse(word64 value) { #if CRYPTOPP_BOOL_SLOW_WORD64 @@ -1935,12 +1935,12 @@ inline word64 BitReverse(word64 value) #endif } -//! \brief Reverses bits in a value -//! \param value the value to reverse -//! \details The template overload of BitReverse operates on signed and unsigned values. -//! Internally the size of T is checked, and then value is cast to a byte, -//! word16, word32 or word64. After the cast, the appropriate BitReverse -//! overload is called. +/// \brief Reverses bits in a value +/// \param value the value to reverse +/// \details The template overload of BitReverse operates on signed and unsigned values. +/// Internally the size of T is checked, and then value is cast to a byte, +/// word16, word32 or word64. After the cast, the appropriate BitReverse +/// overload is called. template inline T BitReverse(T value) { @@ -1957,54 +1957,54 @@ inline T BitReverse(T value) } } -//! \brief Reverses bytes in a value depending upon endianness -//! \tparam T the class or type -//! \param order the ByteOrder of the data -//! \param value the value to conditionally reverse -//! \details Internally, the ConditionalByteReverse calls NativeByteOrderIs. -//! If order matches native byte order, then the original value is returned. -//! If not, then ByteReverse is called on the value before returning to the caller. +/// \brief Reverses bytes in a value depending upon endianness +/// \tparam T the class or type +/// \param order the ByteOrder of the data +/// \param value the value to conditionally reverse +/// \details Internally, the ConditionalByteReverse calls NativeByteOrderIs. +/// If order matches native byte order, then the original value is returned. +/// If not, then ByteReverse is called on the value before returning to the caller. template inline T ConditionalByteReverse(ByteOrder order, T value) { return NativeByteOrderIs(order) ? value : ByteReverse(value); } -//! \brief Reverses bytes in an element from an array of elements -//! \tparam T the class or type -//! \param out the output array of elements -//! \param in the input array of elements -//! \param byteCount the total number of bytes in the array -//! \details Internally, ByteReverse visits each element in the in array -//! calls ByteReverse on it, and writes the result to out. -//! \details ByteReverse does not process tail byes, or bytes that are -//! \a not part of a full element. If T is int (and int is 4 bytes), then -//! byteCount = 10 means only the first 2 elements or 8 bytes are -//! reversed. -//! \details The follwoing program should help illustrate the behavior. -//! 
vector v1, v2;
-//!
-//! v1.push_back(1);
-//! v1.push_back(2);
-//! v1.push_back(3);
-//! v1.push_back(4);
-//!
-//! v2.resize(v1.size());
-//! ByteReverse(&v2[0], &v1[0], 16);
-//!
-//! cout << "V1: ";
-//! for(unsigned int i = 0; i < v1.size(); i++)
-//!   cout << std::hex << v1[i] << " ";
-//! cout << endl;
-//!
-//! cout << "V2: ";
-//! for(unsigned int i = 0; i < v2.size(); i++)
-//!   cout << std::hex << v2[i] << " ";
-//! cout << endl;
-//! The program above results in the follwoing output. -//! 
V1: 00000001 00000002 00000003 00000004
-//! V2: 01000000 02000000 03000000 04000000
-//! \sa ConditionalByteReverse +/// \brief Reverses bytes in an element from an array of elements +/// \tparam T the class or type +/// \param out the output array of elements +/// \param in the input array of elements +/// \param byteCount the total number of bytes in the array +/// \details Internally, ByteReverse visits each element in the in array +/// calls ByteReverse on it, and writes the result to out. +/// \details ByteReverse does not process tail byes, or bytes that are +/// \a not part of a full element. If T is int (and int is 4 bytes), then +/// byteCount = 10 means only the first 2 elements or 8 bytes are +/// reversed. +/// \details The follwoing program should help illustrate the behavior. +/// 
vector v1, v2;
+///
+/// v1.push_back(1);
+/// v1.push_back(2);
+/// v1.push_back(3);
+/// v1.push_back(4);
+///
+/// v2.resize(v1.size());
+/// ByteReverse(&v2[0], &v1[0], 16);
+///
+/// cout << "V1: ";
+/// for(unsigned int i = 0; i < v1.size(); i++)
+///   cout << std::hex << v1[i] << " ";
+/// cout << endl;
+///
+/// cout << "V2: ";
+/// for(unsigned int i = 0; i < v2.size(); i++)
+///   cout << std::hex << v2[i] << " ";
+/// cout << endl;
+/// The program above results in the follwoing output. +/// 
V1: 00000001 00000002 00000003 00000004
+/// V2: 01000000 02000000 03000000 04000000
+/// \sa ConditionalByteReverse template void ByteReverse(T *out, const T *in, size_t byteCount) { @@ -2014,19 +2014,19 @@ void ByteReverse(T *out, const T *in, size_t byteCount) out[i] = ByteReverse(in[i]); } -//! \brief Conditionally reverses bytes in an element from an array of elements -//! \tparam T the class or type -//! \param order the ByteOrder of the data -//! \param out the output array of elements -//! \param in the input array of elements -//! \param byteCount the byte count of the arrays -//! \details Internally, ByteReverse visits each element in the in array -//! calls ByteReverse on it depending on the desired endianness, and writes the result to out. -//! \details ByteReverse does not process tail byes, or bytes that are -//! \a not part of a full element. If T is int (and int is 4 bytes), then -//! byteCount = 10 means only the first 2 elements or 8 bytes are -//! reversed. -//! \sa ByteReverse +/// \brief Conditionally reverses bytes in an element from an array of elements +/// \tparam T the class or type +/// \param order the ByteOrder of the data +/// \param out the output array of elements +/// \param in the input array of elements +/// \param byteCount the byte count of the arrays +/// \details Internally, ByteReverse visits each element in the in array +/// calls ByteReverse on it depending on the desired endianness, and writes the result to out. +/// \details ByteReverse does not process tail byes, or bytes that are +/// \a not part of a full element. If T is int (and int is 4 bytes), then +/// byteCount = 10 means only the first 2 elements or 8 bytes are +/// reversed. +/// \sa ByteReverse template inline void ConditionalByteReverse(ByteOrder order, T *out, const T *in, size_t byteCount) { @@ -2219,22 +2219,22 @@ inline void UnalignedbyteNonTemplate(ByteOrder order, byte *block, word64 value, } #endif // #ifndef CRYPTOPP_ALLOW_UNALIGNED_DATA_ACCESS -//! \brief Access a block of memory -//! \tparam T class or type -//! \param assumeAligned flag indicating alignment -//! \param order the ByteOrder of the data -//! \param block the byte buffer to be processed -//! \returns the word in the specified byte order -//! \details GetWord() provides alternate read access to a block of memory. The flag assumeAligned indicates -//! if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or -//! LITTLE_ENDIAN_ORDER. -//! \details An example of reading two word32 values from a block of memory is shown below. w -//! will be 0x03020100. -//! 
-//!    word32 w;
-//!    byte buffer[4] = {0,1,2,3};
-//!    w = GetWord(false, LITTLE_ENDIAN_ORDER, buffer);
-//!
+/// \brief Access a block of memory +/// \tparam T class or type +/// \param assumeAligned flag indicating alignment +/// \param order the ByteOrder of the data +/// \param block the byte buffer to be processed +/// \returns the word in the specified byte order +/// \details GetWord() provides alternate read access to a block of memory. The flag assumeAligned indicates +/// if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or +/// LITTLE_ENDIAN_ORDER. +/// \details An example of reading two word32 values from a block of memory is shown below. w +/// will be 0x03020100. +/// 
+///    word32 w;
+///    byte buffer[4] = {0,1,2,3};
+///    w = GetWord(false, LITTLE_ENDIAN_ORDER, buffer);
+///
template inline T GetWord(bool assumeAligned, ByteOrder order, const byte *block) { @@ -2248,38 +2248,38 @@ inline T GetWord(bool assumeAligned, ByteOrder order, const byte *block) #endif } -//! \brief Access a block of memory -//! \tparam T class or type -//! \param assumeAligned flag indicating alignment -//! \param order the ByteOrder of the data -//! \param result the word in the specified byte order -//! \param block the byte buffer to be processed -//! \details GetWord() provides alternate read access to a block of memory. The flag assumeAligned indicates -//! if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or -//! LITTLE_ENDIAN_ORDER. -//! \details An example of reading two word32 values from a block of memory is shown below. w -//! will be 0x03020100. -//! 
-//!    word32 w;
-//!    byte buffer[4] = {0,1,2,3};
-//!    w = GetWord(false, LITTLE_ENDIAN_ORDER, buffer);
-//!
+/// \brief Access a block of memory +/// \tparam T class or type +/// \param assumeAligned flag indicating alignment +/// \param order the ByteOrder of the data +/// \param result the word in the specified byte order +/// \param block the byte buffer to be processed +/// \details GetWord() provides alternate read access to a block of memory. The flag assumeAligned indicates +/// if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or +/// LITTLE_ENDIAN_ORDER. +/// \details An example of reading two word32 values from a block of memory is shown below. w +/// will be 0x03020100. +/// 
+///    word32 w;
+///    byte buffer[4] = {0,1,2,3};
+///    w = GetWord(false, LITTLE_ENDIAN_ORDER, buffer);
+///
template inline void GetWord(bool assumeAligned, ByteOrder order, T &result, const byte *block) { result = GetWord(assumeAligned, order, block); } -//! \brief Access a block of memory -//! \tparam T class or type -//! \param assumeAligned flag indicating alignment -//! \param order the ByteOrder of the data -//! \param block the destination byte buffer -//! \param value the word in the specified byte order -//! \param xorBlock an optional byte buffer to xor -//! \details PutWord() provides alternate write access to a block of memory. The flag assumeAligned indicates -//! if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or -//! LITTLE_ENDIAN_ORDER. +/// \brief Access a block of memory +/// \tparam T class or type +/// \param assumeAligned flag indicating alignment +/// \param order the ByteOrder of the data +/// \param block the destination byte buffer +/// \param value the word in the specified byte order +/// \param xorBlock an optional byte buffer to xor +/// \details PutWord() provides alternate write access to a block of memory. The flag assumeAligned indicates +/// if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or +/// LITTLE_ENDIAN_ORDER. template inline void PutWord(bool assumeAligned, ByteOrder order, byte *block, T value, const byte *xorBlock = NULLPTR) { @@ -2294,35 +2294,35 @@ inline void PutWord(bool assumeAligned, ByteOrder order, byte *block, T value, c #endif } -//! \class GetBlock -//! \brief Access a block of memory -//! \tparam T class or type -//! \tparam B enumeration indicating endianness -//! \tparam A flag indicating alignment -//! \details GetBlock() provides alternate read access to a block of memory. The enumeration B is -//! BigEndian or LittleEndian. The flag A indicates if the memory block is aligned for class or type T. -//! Repeatedly applying operator() results in advancing in the block of memory. -//! \details An example of reading two word32 values from a block of memory is shown below. w1 -//! will be 0x03020100 and w1 will be 0x07060504. -//! 
-//!    word32 w1, w2;
-//!    byte buffer[8] = {0,1,2,3,4,5,6,7};
-//!    GetBlock block(buffer);
-//!    block(w1)(w2);
-//!
+/// \class GetBlock +/// \brief Access a block of memory +/// \tparam T class or type +/// \tparam B enumeration indicating endianness +/// \tparam A flag indicating alignment +/// \details GetBlock() provides alternate read access to a block of memory. The enumeration B is +/// BigEndian or LittleEndian. The flag A indicates if the memory block is aligned for class or type T. +/// Repeatedly applying operator() results in advancing in the block of memory. +/// \details An example of reading two word32 values from a block of memory is shown below. w1 +/// will be 0x03020100 and w1 will be 0x07060504. +/// 
+///    word32 w1, w2;
+///    byte buffer[8] = {0,1,2,3,4,5,6,7};
+///    GetBlock block(buffer);
+///    block(w1)(w2);
+///
template class GetBlock { public: - //! \brief Construct a GetBlock - //! \param block the memory block + /// \brief Construct a GetBlock + /// \param block the memory block GetBlock(const void *block) : m_block((const byte *)block) {} - //! \brief Access a block of memory - //! \tparam U class or type - //! \param x the value to read - //! \returns pointer to the remainder of the block after reading x + /// \brief Access a block of memory + /// \tparam U class or type + /// \param x the value to read + /// \returns pointer to the remainder of the block after reading x template inline GetBlock & operator()(U &x) { @@ -2336,36 +2336,36 @@ private: const byte *m_block; }; -//! \class PutBlock -//! \brief Access a block of memory -//! \tparam T class or type -//! \tparam B enumeration indicating endianness -//! \tparam A flag indicating alignment -//! \details PutBlock() provides alternate write access to a block of memory. The enumeration B is -//! BigEndian or LittleEndian. The flag A indicates if the memory block is aligned for class or type T. -//! Repeatedly applying operator() results in advancing in the block of memory. -//! \details An example of writing two word32 values from a block of memory is shown below. After the code -//! executes, the byte buffer will be {0,1,2,3,4,5,6,7}. -//! 
-//!    word32 w1=0x03020100, w2=0x07060504;
-//!    byte buffer[8];
-//!    PutBlock block(NULLPTR, buffer);
-//!    block(w1)(w2);
-//!
+/// \class PutBlock +/// \brief Access a block of memory +/// \tparam T class or type +/// \tparam B enumeration indicating endianness +/// \tparam A flag indicating alignment +/// \details PutBlock() provides alternate write access to a block of memory. The enumeration B is +/// BigEndian or LittleEndian. The flag A indicates if the memory block is aligned for class or type T. +/// Repeatedly applying operator() results in advancing in the block of memory. +/// \details An example of writing two word32 values from a block of memory is shown below. After the code +/// executes, the byte buffer will be {0,1,2,3,4,5,6,7}. +/// 
+///    word32 w1=0x03020100, w2=0x07060504;
+///    byte buffer[8];
+///    PutBlock block(NULLPTR, buffer);
+///    block(w1)(w2);
+///
template class PutBlock { public: - //! \brief Construct a PutBlock - //! \param block the memory block - //! \param xorBlock optional mask + /// \brief Construct a PutBlock + /// \param block the memory block + /// \param xorBlock optional mask PutBlock(const void *xorBlock, void *block) : m_xorBlock((const byte *)xorBlock), m_block((byte *)block) {} - //! \brief Access a block of memory - //! \tparam U class or type - //! \param x the value to write - //! \returns pointer to the remainder of the block after writing x + /// \brief Access a block of memory + /// \tparam U class or type + /// \param x the value to write + /// \returns pointer to the remainder of the block after writing x template inline PutBlock & operator()(U x) { @@ -2381,15 +2381,15 @@ private: byte *m_block; }; -//! \class BlockGetAndPut -//! \brief Access a block of memory -//! \tparam T class or type -//! \tparam B enumeration indicating endianness -//! \tparam GA flag indicating alignment for the Get operation -//! \tparam PA flag indicating alignment for the Put operation -//! \details GetBlock() provides alternate write access to a block of memory. The enumeration B is -//! BigEndian or LittleEndian. The flag A indicates if the memory block is aligned for class or type T. -//! \sa GetBlock() and PutBlock(). +/// \class BlockGetAndPut +/// \brief Access a block of memory +/// \tparam T class or type +/// \tparam B enumeration indicating endianness +/// \tparam GA flag indicating alignment for the Get operation +/// \tparam PA flag indicating alignment for the Put operation +/// \details GetBlock() provides alternate write access to a block of memory. The enumeration B is +/// BigEndian or LittleEndian. The flag A indicates if the memory block is aligned for class or type T. +/// \sa GetBlock() and PutBlock(). template struct BlockGetAndPut { @@ -2417,26 +2417,26 @@ T StringToWord(const std::string &str, ByteOrder order = BIG_ENDIAN_ORDER) // ************** help remove warning on g++ *************** -//! \class SafeShifter -//! \brief Safely shift values when undefined behavior could occur -//! \tparam overflow boolean flag indicating if overflow is present -//! \details SafeShifter safely shifts values when undefined behavior could occur under C/C++ rules. -//! The class behaves much like a saturating arithmetic class, clamping values rather than allowing -//! the compiler to remove undefined behavior. -//! \sa SafeShifter, SafeShifter +/// \class SafeShifter +/// \brief Safely shift values when undefined behavior could occur +/// \tparam overflow boolean flag indicating if overflow is present +/// \details SafeShifter safely shifts values when undefined behavior could occur under C/C++ rules. +/// The class behaves much like a saturating arithmetic class, clamping values rather than allowing +/// the compiler to remove undefined behavior. +/// \sa SafeShifter, SafeShifter template struct SafeShifter; -//! \class SafeShifter -//! \brief Shifts a value in the presence of overflow -//! \details the \p true template parameter indicates overflow would occur. -//! In this case, SafeShifter clamps the value and returns 0. +/// \class SafeShifter +/// \brief Shifts a value in the presence of overflow +/// \details the \p true template parameter indicates overflow would occur. +/// In this case, SafeShifter clamps the value and returns 0. template<> struct SafeShifter { - //! \brief Right shifts a value that overflows - //! \tparam T class or type - //! \return 0 - //! \details Since overflow == true, the value 0 is always returned. - //! \sa SafeLeftShift + /// \brief Right shifts a value that overflows + /// \tparam T class or type + /// \return 0 + /// \details Since overflow == true, the value 0 is always returned. + /// \sa SafeLeftShift template static inline T RightShift(T value, unsigned int bits) { @@ -2444,11 +2444,11 @@ template<> struct SafeShifter return 0; } - //! \brief Left shifts a value that overflows - //! \tparam T class or type - //! \return 0 - //! \details Since overflow == true, the value 0 is always returned. - //! \sa SafeRightShift + /// \brief Left shifts a value that overflows + /// \tparam T class or type + /// \return 0 + /// \details Since overflow == true, the value 0 is always returned. + /// \sa SafeRightShift template static inline T LeftShift(T value, unsigned int bits) { @@ -2457,28 +2457,28 @@ template<> struct SafeShifter } }; -//! \class SafeShifter -//! \brief Shifts a value in the absence of overflow -//! \details the \p false template parameter indicates overflow would \a not occur. -//! In this case, SafeShifter returns the shfted value. +/// \class SafeShifter +/// \brief Shifts a value in the absence of overflow +/// \details the \p false template parameter indicates overflow would \a not occur. +/// In this case, SafeShifter returns the shfted value. template<> struct SafeShifter { - //! \brief Right shifts a value that does not overflow - //! \tparam T class or type - //! \return the shifted value - //! \details Since overflow == false, the shifted value is returned. - //! \sa SafeLeftShift + /// \brief Right shifts a value that does not overflow + /// \tparam T class or type + /// \return the shifted value + /// \details Since overflow == false, the shifted value is returned. + /// \sa SafeLeftShift template static inline T RightShift(T value, unsigned int bits) { return value >> bits; } - //! \brief Left shifts a value that does not overflow - //! \tparam T class or type - //! \return the shifted value - //! \details Since overflow == false, the shifted value is returned. - //! \sa SafeRightShift + /// \brief Left shifts a value that does not overflow + /// \tparam T class or type + /// \return the shifted value + /// \details Since overflow == false, the shifted value is returned. + /// \sa SafeRightShift template static inline T LeftShift(T value, unsigned int bits) { @@ -2486,28 +2486,28 @@ template<> struct SafeShifter } }; -//! \brief Safely right shift values when undefined behavior could occur -//! \tparam bits the number of bit positions to shift the value -//! \tparam T class or type -//! \param value the value to right shift -//! \result the shifted value or 0 -//! \details SafeRightShift safely shifts the value to the right when undefined behavior -//! could occur under C/C++ rules. SafeRightShift will return the shifted value or 0 -//! if undefined behavior would occur. +/// \brief Safely right shift values when undefined behavior could occur +/// \tparam bits the number of bit positions to shift the value +/// \tparam T class or type +/// \param value the value to right shift +/// \result the shifted value or 0 +/// \details SafeRightShift safely shifts the value to the right when undefined behavior +/// could occur under C/C++ rules. SafeRightShift will return the shifted value or 0 +/// if undefined behavior would occur. template inline T SafeRightShift(T value) { return SafeShifter<(bits>=(8*sizeof(T)))>::RightShift(value, bits); } -//! \brief Safely left shift values when undefined behavior could occur -//! \tparam bits the number of bit positions to shift the value -//! \tparam T class or type -//! \param value the value to left shift -//! \result the shifted value or 0 -//! \details SafeLeftShift safely shifts the value to the left when undefined behavior -//! could occur under C/C++ rules. SafeLeftShift will return the shifted value or 0 -//! if undefined behavior would occur. +/// \brief Safely left shift values when undefined behavior could occur +/// \tparam bits the number of bit positions to shift the value +/// \tparam T class or type +/// \param value the value to left shift +/// \result the shifted value or 0 +/// \details SafeLeftShift safely shifts the value to the left when undefined behavior +/// could occur under C/C++ rules. SafeLeftShift will return the shifted value or 0 +/// if undefined behavior would occur. template inline T SafeLeftShift(T value) { diff --git a/modarith.h b/modarith.h index 1a78f535..709a9121 100644 --- a/modarith.h +++ b/modarith.h @@ -1,7 +1,7 @@ // modarith.h - originally written and placed in the public domain by Wei Dai -//! \file modarith.h -//! \brief Class file for performing modular arithmetic. +/// \file modarith.h +/// \brief Class file for performing modular arithmetic. #ifndef CRYPTOPP_MODARITH_H #define CRYPTOPP_MODARITH_H @@ -25,17 +25,17 @@ CRYPTOPP_DLL_TEMPLATE_CLASS AbstractGroup; CRYPTOPP_DLL_TEMPLATE_CLASS AbstractRing; CRYPTOPP_DLL_TEMPLATE_CLASS AbstractEuclideanDomain; -//! \class ModularArithmetic -//! \brief Ring of congruence classes modulo n -//! \details This implementation represents each congruence class as the smallest -//! non-negative integer in that class. -//! \details const Element& returned by member functions are references -//! to internal data members. Since each object may have only -//! one such data member for holding results, the following code -//! will produce incorrect results: -//! 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
-//! But this should be fine: -//! 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
+/// \class ModularArithmetic +/// \brief Ring of congruence classes modulo n +/// \details This implementation represents each congruence class as the smallest +/// non-negative integer in that class. +/// \details const Element& returned by member functions are references +/// to internal data members. Since each object may have only +/// one such data member for holding results, the following code +/// will produce incorrect results: +/// 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
+/// But this should be fine: +/// 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
class CRYPTOPP_DLL ModularArithmetic : public AbstractRing { public: @@ -45,201 +45,201 @@ public: virtual ~ModularArithmetic() {} - //! \brief Construct a ModularArithmetic - //! \param modulus congruence class modulus + /// \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 + /// \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 + /// \brief Construct a ModularArithmetic + /// \param bt BER encoded ModularArithmetic ModularArithmetic(BufferedTransformation &bt); // construct from BER encoded parameters - //! \brief Clone a ModularArithmetic - //! \returns pointer to a new ModularArithmetic - //! \details Clone effectively copy constructs a new ModularArithmetic. The caller is - //! responsible for deleting the pointer returned from this method. + /// \brief Clone a ModularArithmetic + /// \returns pointer to a new ModularArithmetic + /// \details Clone effectively copy constructs a new ModularArithmetic. The caller is + /// responsible for deleting the pointer returned from this method. virtual ModularArithmetic * Clone() const {return new ModularArithmetic(*this);} - //! \brief Encodes in DER format - //! \param bt BufferedTransformation object + /// \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 + /// \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 + /// \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 + /// \brief Retrieves the modulus + /// \returns the modulus const Integer& GetModulus() const {return m_modulus;} - //! \brief Sets the modulus - //! \param newModulus the new 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 if the modulus is in Montgomery form for multiplication, false otherwise + /// \brief Retrieves the representation + /// \returns true if the if the modulus is in Montgomery form for multiplication, 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. + /// \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. + /// \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 Divides an element by 2 - //! \param a element to convert + /// \brief Divides an element by 2 + /// \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 + /// \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 + /// \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 + /// \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 + /// \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 + /// \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. + /// \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 + /// \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. + /// \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. + /// \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 the multiplicand - //! \param b the multiplier - //! \returns the product of a and b - //! \details Multiply returns a*b\%n. + /// \brief Multiplies elements in the ring + /// \param a the multiplicand + /// \param b the multiplier + /// \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. + /// \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. + /// \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. + /// \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 the dividend - //! \param b the divisor - //! \returns the quotient - //! \details Divide returns a*b-1\%n. + /// \brief Divides elements in the ring + /// \param a the dividend + /// \param b the divisor + /// \returns the quotient + /// \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 + /// \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 + /// \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 + /// \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 + /// \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();} - //! \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). + /// \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 { @@ -247,10 +247,10 @@ public: 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. + /// \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;} @@ -263,30 +263,30 @@ protected: // const ModularArithmetic::RandomizationParameter ModularArithmetic::DefaultRandomizationParameter = 0 ; -//! \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. -//! \details const Element& returned by member functions are references to -//! internal data members. Since each object may have only one such data member for holding -//! results, the following code will produce incorrect results: -//! 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
-//! But this should be fine: -//! 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
+/// \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. +/// \details const Element& returned by member functions are references to +/// internal data members. Since each object may have only one such data member for holding +/// results, the following code will produce incorrect results: +/// 
    abcd = group.Add(group.Add(a,b), group.Add(c,d));
+/// But this should be fine: +/// 
    abcd = group.Add(a, group.Add(b, group.Add(c,d));
class CRYPTOPP_DLL MontgomeryRepresentation : public ModularArithmetic { public: virtual ~MontgomeryRepresentation() {} - //! \brief Construct a MontgomeryRepresentation - //! \param modulus congruence class modulus - //! \note The modulus must be odd. + /// \brief Construct a MontgomeryRepresentation + /// \param modulus congruence class modulus + /// \note The modulus must be odd. MontgomeryRepresentation(const Integer &modulus); - //! \brief Clone a MontgomeryRepresentation - //! \returns pointer to a new MontgomeryRepresentation - //! \details Clone effectively copy constructs a new MontgomeryRepresentation. The caller is - //! responsible for deleting the pointer returned from this method. + /// \brief Clone a MontgomeryRepresentation + /// \returns pointer to a new MontgomeryRepresentation + /// \details Clone effectively copy constructs a new MontgomeryRepresentation. The caller is + /// responsible for deleting the pointer returned from this method. virtual ModularArithmetic * Clone() const {return new MontgomeryRepresentation(*this);} bool IsMontgomeryRepresentation() const {return true;} diff --git a/modes.h b/modes.h index 7e72d95e..b153cb5d 100644 --- a/modes.h +++ b/modes.h @@ -1,7 +1,7 @@ // modes.h - originally written and placed in the public domain by Wei Dai -//! \file modes.h -//! \brief Classes for block cipher modes of operation +/// \file modes.h +/// \brief Classes for block cipher modes of operation #ifndef CRYPTOPP_MODES_H #define CRYPTOPP_MODES_H @@ -30,24 +30,24 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class CipherModeDocumentation -//! \brief Block cipher mode of operation information -//! \details Each class derived from this one defines two types, Encryption and Decryption, -//! both of which implement the SymmetricCipher interface. -//! For each mode there are two classes, one of which is a template class, -//! and the other one has a name that ends in "_ExternalCipher". -//! The "external cipher" mode objects hold a reference to the underlying block cipher, -//! instead of holding an instance of it. The reference must be passed in to the constructor. -//! For the "cipher holder" classes, the CIPHER template parameter should be a class -//! derived from BlockCipherDocumentation, for example DES or AES. -//! \details See NIST SP 800-38A for definitions of these modes. See -//! AuthenticatedSymmetricCipherDocumentation for authenticated encryption modes. +/// \class CipherModeDocumentation +/// \brief Block cipher mode of operation information +/// \details Each class derived from this one defines two types, Encryption and Decryption, +/// both of which implement the SymmetricCipher interface. +/// For each mode there are two classes, one of which is a template class, +/// and the other one has a name that ends in "_ExternalCipher". +/// The "external cipher" mode objects hold a reference to the underlying block cipher, +/// instead of holding an instance of it. The reference must be passed in to the constructor. +/// For the "cipher holder" classes, the CIPHER template parameter should be a class +/// derived from BlockCipherDocumentation, for example DES or AES. +/// \details See NIST SP 800-38A for definitions of these modes. See +/// AuthenticatedSymmetricCipherDocumentation for authenticated encryption modes. struct CipherModeDocumentation : public SymmetricCipherDocumentation { }; -//! \class CipherModeBase -//! \brief Block cipher mode of operation information +/// \class CipherModeBase +/// \brief Block cipher mode of operation information class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CipherModeBase : public SymmetricCipher { public: @@ -95,9 +95,9 @@ protected: AlignedSecByteBlock m_register; }; -//! \class ModePolicyCommonTemplate -//! \brief Block cipher mode of operation common operations -//! \tparam POLICY_INTERFACE common operations +/// \class ModePolicyCommonTemplate +/// \brief Block cipher mode of operation common operations +/// \tparam POLICY_INTERFACE common operations template class CRYPTOPP_NO_VTABLE ModePolicyCommonTemplate : public CipherModeBase, public POLICY_INTERFACE { @@ -114,8 +114,8 @@ void ModePolicyCommonTemplate::CipherSetKey(const NameValuePai SetFeedbackSize(feedbackSize); } -//! \class CFB_ModePolicy -//! \brief CFB block cipher mode of operation +/// \class CFB_ModePolicy +/// \brief CFB block cipher mode of operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CFB_ModePolicy : public ModePolicyCommonTemplate { public: @@ -149,8 +149,8 @@ inline void CopyOrZero(void *dest, size_t d, const void *src, size_t s) memset(dest, 0, d); } -//! \class OFB_ModePolicy -//! \brief OFB block cipher mode of operation +/// \class OFB_ModePolicy +/// \brief OFB block cipher mode of operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE OFB_ModePolicy : public ModePolicyCommonTemplate { public: @@ -166,8 +166,8 @@ private: void CipherResynchronize(byte *keystreamBuffer, const byte *iv, size_t length); }; -//! \class CTR_ModePolicy -//! \brief CTR block cipher mode of operation +/// \class CTR_ModePolicy +/// \brief CTR block cipher mode of operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CTR_ModePolicy : public ModePolicyCommonTemplate { public: @@ -192,8 +192,8 @@ protected: AlignedSecByteBlock m_counterArray; }; -//! \class BlockOrientedCipherModeBase -//! \brief Block cipher mode of operation default implementation +/// \class BlockOrientedCipherModeBase +/// \brief Block cipher mode of operation default implementation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE BlockOrientedCipherModeBase : public CipherModeBase { public: @@ -212,8 +212,8 @@ protected: SecByteBlock m_buffer; }; -//! \class ECB_OneWay -//! \brief ECB block cipher mode of operation default implementation +/// \class ECB_OneWay +/// \brief ECB block cipher mode of operation default implementation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE ECB_OneWay : public BlockOrientedCipherModeBase { public: @@ -226,8 +226,8 @@ public: void ProcessData(byte *outString, const byte *inString, size_t length); }; -//! \class CBC_ModeBase -//! \brief CBC block cipher mode of operation default implementation +/// \class CBC_ModeBase +/// \brief CBC block cipher mode of operation default implementation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CBC_ModeBase : public BlockOrientedCipherModeBase { public: @@ -238,16 +238,16 @@ public: unsigned int MinLastBlockSize() const {return 0;} }; -//! \class CBC_Encryption -//! \brief CBC block cipher mode of operation encryption operation +/// \class CBC_Encryption +/// \brief CBC block cipher mode of operation encryption operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CBC_Encryption : public CBC_ModeBase { public: void ProcessData(byte *outString, const byte *inString, size_t length); }; -//! \class CBC_CTS_Encryption -//! \brief CBC-CTS block cipher mode of operation encryption operation +/// \class CBC_CTS_Encryption +/// \brief CBC-CTS block cipher mode of operation encryption operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CBC_CTS_Encryption : public CBC_Encryption { public: @@ -267,8 +267,8 @@ protected: byte *m_stolenIV; }; -//! \class CBC_Decryption -//! \brief CBC block cipher mode of operation decryption operation +/// \class CBC_Decryption +/// \brief CBC block cipher mode of operation decryption operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CBC_Decryption : public CBC_ModeBase { public: @@ -281,8 +281,8 @@ protected: AlignedSecByteBlock m_temp; }; -//! \class CBC_CTS_Decryption -//! \brief CBC-CTS block cipher mode of operation decryption operation +/// \class CBC_CTS_Decryption +/// \brief CBC-CTS block cipher mode of operation decryption operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CBC_CTS_Decryption : public CBC_Decryption { public: @@ -290,8 +290,8 @@ public: size_t ProcessLastBlock(byte *outString, size_t outLength, const byte *inString, size_t inLength); }; -//! \class CipherModeFinalTemplate_CipherHolder -//! \brief Block cipher mode of operation aggregate +/// \class CipherModeFinalTemplate_CipherHolder +/// \brief Block cipher mode of operation aggregate template class CipherModeFinalTemplate_CipherHolder : protected ObjectHolder, public AlgorithmImpl > { @@ -321,9 +321,9 @@ public: } }; -//! \class CipherModeFinalTemplate_ExternalCipher -//! \tparam BASE CipherModeFinalTemplate_CipherHolder base class -//! \details Base class for external mode cipher combinations +/// \class CipherModeFinalTemplate_ExternalCipher +/// \tparam BASE CipherModeFinalTemplate_CipherHolder base class +/// \details Base class for external mode cipher combinations template class CipherModeFinalTemplate_ExternalCipher : public BASE { @@ -342,10 +342,10 @@ CRYPTOPP_DLL_TEMPLATE_CLASS CFB_CipherTemplate >; CRYPTOPP_DLL_TEMPLATE_CLASS CFB_DecryptionTemplate >; -//! \class CFB_Mode -//! \brief CFB block cipher mode of operation -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CFB_Mode +/// \brief CFB block cipher mode of operation +/// \sa Modes of Operation +/// on the Crypto++ wiki. template struct CFB_Mode : public CipherModeDocumentation { @@ -353,21 +353,21 @@ struct CFB_Mode : public CipherModeDocumentation typedef CipherModeFinalTemplate_CipherHolder > > > Decryption; }; -//! \class CFB_Mode_ExternalCipher -//! \brief CFB mode, external cipher. -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CFB_Mode_ExternalCipher +/// \brief CFB mode, external cipher. +/// \sa Modes of Operation +/// on the Crypto++ wiki. struct CFB_Mode_ExternalCipher : public CipherModeDocumentation { typedef CipherModeFinalTemplate_ExternalCipher > > > Encryption; typedef CipherModeFinalTemplate_ExternalCipher > > > Decryption; }; -//! \class CFB_FIPS_Mode -//! \brief CFB block cipher mode of operation providing FIPS validated cryptography. -//! \details Requires full block plaintext according to FIPS 800-38A -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CFB_FIPS_Mode +/// \brief CFB block cipher mode of operation providing FIPS validated cryptography. +/// \details Requires full block plaintext according to FIPS 800-38A +/// \sa Modes of Operation +/// on the Crypto++ wiki. template struct CFB_FIPS_Mode : public CipherModeDocumentation { @@ -375,11 +375,11 @@ struct CFB_FIPS_Mode : public CipherModeDocumentation typedef CipherModeFinalTemplate_CipherHolder > > > > Decryption; }; -//! \class CFB_FIPS_Mode_ExternalCipher -//! \brief CFB mode, external cipher, providing FIPS validated cryptography. -//! \details Requires full block plaintext according to FIPS 800-38A -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CFB_FIPS_Mode_ExternalCipher +/// \brief CFB mode, external cipher, providing FIPS validated cryptography. +/// \details Requires full block plaintext according to FIPS 800-38A +/// \sa Modes of Operation +/// on the Crypto++ wiki. struct CFB_FIPS_Mode_ExternalCipher : public CipherModeDocumentation { typedef CipherModeFinalTemplate_ExternalCipher > > > > Encryption; @@ -388,10 +388,10 @@ struct CFB_FIPS_Mode_ExternalCipher : public CipherModeDocumentation CRYPTOPP_DLL_TEMPLATE_CLASS AdditiveCipherTemplate >; -//! \class OFB_Mode -//! \brief OFB block cipher mode of operation -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class OFB_Mode +/// \brief OFB block cipher mode of operation +/// \sa Modes of Operation +/// on the Crypto++ wiki. template struct OFB_Mode : public CipherModeDocumentation { @@ -399,10 +399,10 @@ struct OFB_Mode : public CipherModeDocumentation typedef Encryption Decryption; }; -//! \class OFB_Mode_ExternalCipher -//! \brief OFB mode, external cipher. -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class OFB_Mode_ExternalCipher +/// \brief OFB mode, external cipher. +/// \sa Modes of Operation +/// on the Crypto++ wiki. struct OFB_Mode_ExternalCipher : public CipherModeDocumentation { typedef CipherModeFinalTemplate_ExternalCipher > > > Encryption; @@ -412,10 +412,10 @@ struct OFB_Mode_ExternalCipher : public CipherModeDocumentation CRYPTOPP_DLL_TEMPLATE_CLASS AdditiveCipherTemplate >; CRYPTOPP_DLL_TEMPLATE_CLASS CipherModeFinalTemplate_ExternalCipher > > >; -//! \class CTR_Mode -//! \brief CTR block cipher mode of operation -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CTR_Mode +/// \brief CTR block cipher mode of operation +/// \sa Modes of Operation +/// on the Crypto++ wiki. template struct CTR_Mode : public CipherModeDocumentation { @@ -423,20 +423,20 @@ struct CTR_Mode : public CipherModeDocumentation typedef Encryption Decryption; }; -//! \class CTR_Mode_ExternalCipher -//! \brief CTR mode, external cipher. -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CTR_Mode_ExternalCipher +/// \brief CTR mode, external cipher. +/// \sa Modes of Operation +/// on the Crypto++ wiki. struct CTR_Mode_ExternalCipher : public CipherModeDocumentation { typedef CipherModeFinalTemplate_ExternalCipher > > > Encryption; typedef Encryption Decryption; }; -//! \class ECB_Mode -//! \brief ECB block cipher mode of operation -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class ECB_Mode +/// \brief ECB block cipher mode of operation +/// \sa Modes of Operation +/// on the Crypto++ wiki. template struct ECB_Mode : public CipherModeDocumentation { @@ -446,20 +446,20 @@ struct ECB_Mode : public CipherModeDocumentation CRYPTOPP_DLL_TEMPLATE_CLASS CipherModeFinalTemplate_ExternalCipher; -//! \class ECB_Mode_ExternalCipher -//! \brief ECB mode, external cipher. -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class ECB_Mode_ExternalCipher +/// \brief ECB mode, external cipher. +/// \sa Modes of Operation +/// on the Crypto++ wiki. struct ECB_Mode_ExternalCipher : public CipherModeDocumentation { typedef CipherModeFinalTemplate_ExternalCipher Encryption; typedef Encryption Decryption; }; -//! \class CBC_Mode -//! \brief CBC block cipher mode of operation -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CBC_Mode +/// \brief CBC block cipher mode of operation +/// \sa Modes of Operation +/// on the Crypto++ wiki. template struct CBC_Mode : public CipherModeDocumentation { @@ -470,20 +470,20 @@ struct CBC_Mode : public CipherModeDocumentation CRYPTOPP_DLL_TEMPLATE_CLASS CipherModeFinalTemplate_ExternalCipher; CRYPTOPP_DLL_TEMPLATE_CLASS CipherModeFinalTemplate_ExternalCipher; -//! \class CBC_Mode_ExternalCipher -//! \brief CBC mode, external cipher -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CBC_Mode_ExternalCipher +/// \brief CBC mode, external cipher +/// \sa Modes of Operation +/// on the Crypto++ wiki. struct CBC_Mode_ExternalCipher : public CipherModeDocumentation { typedef CipherModeFinalTemplate_ExternalCipher Encryption; typedef CipherModeFinalTemplate_ExternalCipher Decryption; }; -//! \class CBC_CTS_Mode -//! \brief CBC-CTS block cipher mode of operation -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CBC_CTS_Mode +/// \brief CBC-CTS block cipher mode of operation +/// \sa Modes of Operation +/// on the Crypto++ wiki. template struct CBC_CTS_Mode : public CipherModeDocumentation { @@ -494,10 +494,10 @@ struct CBC_CTS_Mode : public CipherModeDocumentation CRYPTOPP_DLL_TEMPLATE_CLASS CipherModeFinalTemplate_ExternalCipher; CRYPTOPP_DLL_TEMPLATE_CLASS CipherModeFinalTemplate_ExternalCipher; -//! \class CBC_CTS_Mode_ExternalCipher -//! \brief CBC mode with ciphertext stealing, external cipher -//! \sa Modes of Operation -//! on the Crypto++ wiki. +/// \class CBC_CTS_Mode_ExternalCipher +/// \brief CBC mode with ciphertext stealing, external cipher +/// \sa Modes of Operation +/// on the Crypto++ wiki. struct CBC_CTS_Mode_ExternalCipher : public CipherModeDocumentation { typedef CipherModeFinalTemplate_ExternalCipher Encryption; diff --git a/mqueue.h b/mqueue.h index 5c9bcdc8..1225a3ad 100644 --- a/mqueue.h +++ b/mqueue.h @@ -10,7 +10,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! Message Queue +/// Message Queue class CRYPTOPP_DLL MessageQueue : public AutoSignaling { public: @@ -67,7 +67,7 @@ private: }; -//! A filter that checks messages on two channels for equality +/// A filter that checks messages on two channels for equality class CRYPTOPP_DLL EqualityComparisonFilter : public Unflushable > { public: diff --git a/mqv.h b/mqv.h index c51a8452..23464c3c 100644 --- a/mqv.h +++ b/mqv.h @@ -1,7 +1,7 @@ // mqv.h - originally written and placed in the public domain by Wei Dai -//! \file mqv.h -//! \brief Classes for Menezes–Qu–Vanstone (MQV) key agreement +/// \file mqv.h +/// \brief Classes for Menezes–Qu–Vanstone (MQV) key agreement #ifndef CRYPTOPP_MQV_H #define CRYPTOPP_MQV_H @@ -15,14 +15,14 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class MQV_Domain -//! \brief MQV domain for performing authenticated key agreement -//! \tparam GROUP_PARAMETERS doamin parameters -//! \tparam COFACTOR_OPTION cofactor option -//! \details GROUP_PARAMETERS parameters include the curve coefcients and the base point. -//! Binary curves use a polynomial to represent its characteristic, while prime curves -//! use a prime number. -//! \sa MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain +/// \class MQV_Domain +/// \brief MQV domain for performing authenticated key agreement +/// \tparam GROUP_PARAMETERS doamin parameters +/// \tparam COFACTOR_OPTION cofactor option +/// \details GROUP_PARAMETERS parameters include the curve coefcients and the base point. +/// Binary curves use a polynomial to represent its characteristic, while prime curves +/// use a prime number. +/// \sa MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain template class MQV_Domain : public AuthenticatedKeyAgreementDomain { @@ -31,104 +31,104 @@ public: typedef typename GroupParameters::Element Element; typedef MQV_Domain Domain; - //! \brief Construct a MQV domain + /// \brief Construct a MQV domain MQV_Domain() {} - //! \brief Construct a MQV domain - //! \param params group parameters and options + /// \brief Construct a MQV domain + /// \param params group parameters and options MQV_Domain(const GroupParameters ¶ms) : m_groupParameters(params) {} - //! \brief Construct a MQV domain - //! \param bt BufferedTransformation with group parameters and options + /// \brief Construct a MQV domain + /// \param bt BufferedTransformation with group parameters and options MQV_Domain(BufferedTransformation &bt) {m_groupParameters.BERDecode(bt);} - //! \brief Construct a MQV 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. + /// \brief Construct a MQV 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 MQV_Domain(T1 v1, T2 v2) {m_groupParameters.Initialize(v1, v2);} - //! \brief Construct a MQV 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. + /// \brief Construct a MQV 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 MQV_Domain(T1 v1, T2 v2, T3 v3) {m_groupParameters.Initialize(v1, v2, v3);} - //! \brief Construct a MQV 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 third parameter - //! \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object. + /// \brief Construct a MQV 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 third parameter + /// \details v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object. template MQV_Domain(T1 v1, T2 v2, T3 v3, 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 + /// \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 + /// \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 Retrieves the crypto parameters for this domain - //! \return the crypto parameters for this domain as a non-const reference + /// \brief Retrieves the crypto parameters for this domain + /// \return the crypto parameters for this domain as a non-const reference CryptoParameters & AccessCryptoParameters() {return AccessAbstractGroupParameters();} - //! \brief Provides the size of the agreed value - //! \return size of agreed value produced in this domain - //! \details The length is calculated using GetEncodedElementSize(false), which means the - //! element is encoded in a non-reversible format. A non-reversible format means its a raw byte array, - //! and it lacks presentation format like an ASN.1 BIT_STRING or OCTET_STRING. + /// \brief Provides the size of the agreed value + /// \return size of agreed value produced in this domain + /// \details The length is calculated using GetEncodedElementSize(false), which means the + /// element is encoded in a non-reversible format. A non-reversible format means its a raw byte array, + /// and it lacks presentation format like an ASN.1 BIT_STRING or OCTET_STRING. unsigned int AgreedValueLength() const {return GetAbstractGroupParameters().GetEncodedElementSize(false);} - //! \brief Provides the size of the static private key - //! \return size of static private keys in this domain - //! \details The length is calculated using the byte count of the subgroup order. + /// \brief Provides the size of the static private key + /// \return size of static private keys in this domain + /// \details The length is calculated using the byte count of the subgroup order. unsigned int StaticPrivateKeyLength() const {return GetAbstractGroupParameters().GetSubgroupOrder().ByteCount();} - //! \brief Provides the size of the static public key - //! \return size of static public keys in this domain - //! \details The length is calculated using GetEncodedElementSize(true), which means the - //! element is encoded in a reversible format. A reversible format means it has a presentation format, - //! and its an ANS.1 encoded element or point. + /// \brief Provides the size of the static public key + /// \return size of static public keys in this domain + /// \details The length is calculated using GetEncodedElementSize(true), which means the + /// element is encoded in a reversible format. A reversible format means it has a presentation format, + /// and its an ANS.1 encoded element or point. unsigned int StaticPublicKeyLength() const {return GetAbstractGroupParameters().GetEncodedElementSize(true);} - //! \brief Generate static private key in this domain - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer for the generated private key in this domain - //! \details The private key is a random scalar used as an exponent in the range [1,MaxExponent()]. - //! \pre COUNTOF(privateKey) == PrivateStaticKeyLength() + /// \brief Generate static private key in this domain + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer for the generated private key in this domain + /// \details The private key is a random scalar used as an exponent in the range [1,MaxExponent()]. + /// \pre COUNTOF(privateKey) == PrivateStaticKeyLength() void GenerateStaticPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const { Integer x(rng, Integer::One(), GetAbstractGroupParameters().GetMaxExponent()); x.Encode(privateKey, StaticPrivateKeyLength()); } - //! \brief Generate a static public key from a private key in this domain - //! \param rng a RandomNumberGenerator derived class - //! \param privateKey a byte buffer with the previously generated private key - //! \param publicKey a byte buffer for the generated public key in this domain - //! \details The public key is an element or point on the curve, and its stored in a revrsible format. - //! A reversible format means it has a presentation format, and its an ANS.1 encoded element or point. - //! \pre COUNTOF(publicKey) == PublicStaticKeyLength() + /// \brief Generate a static public key from a private key in this domain + /// \param rng a RandomNumberGenerator derived class + /// \param privateKey a byte buffer with the previously generated private key + /// \param publicKey a byte buffer for the generated public key in this domain + /// \details The public key is an element or point on the curve, and its stored in a revrsible format. + /// A reversible format means it has a presentation format, and its an ANS.1 encoded element or point. + /// \pre COUNTOF(publicKey) == PublicStaticKeyLength() void GenerateStaticPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const { CRYPTOPP_UNUSED(rng); @@ -212,8 +212,8 @@ private: GroupParameters m_groupParameters; }; -//! Menezes-Qu-Vanstone in GF(p) with key validation, AKA MQV -//! \sa MQV, HMQV_Domain, FHMQV_Domain, AuthenticatedKeyAgreementDomain +/// Menezes-Qu-Vanstone in GF(p) with key validation, AKA MQV +/// \sa MQV, HMQV_Domain, FHMQV_Domain, AuthenticatedKeyAgreementDomain typedef MQV_Domain MQV; NAMESPACE_END diff --git a/nbtheory.h b/nbtheory.h index 8d7e4714..6048eaac 100644 --- a/nbtheory.h +++ b/nbtheory.h @@ -1,7 +1,7 @@ // nbtheory.h - originally written and placed in the public domain by Wei Dai -//! \file nbtheory.h -//! \brief Classes and functions for number theoretic operations +/// \file nbtheory.h +/// \brief Classes and functions for number theoretic operations #ifndef CRYPTOPP_NBTHEORY_H #define CRYPTOPP_NBTHEORY_H @@ -17,31 +17,31 @@ CRYPTOPP_DLL const word16 * CRYPTOPP_API GetPrimeTable(unsigned int &size); // ************ primality testing **************** -//! \brief Generates a provable prime -//! \param rng a RandomNumberGenerator to produce keying material -//! \param bits the number of bits in the prime number -//! \returns Integer() meeting Maurer's tests for primality +/// \brief Generates a provable prime +/// \param rng a RandomNumberGenerator to produce keying material +/// \param bits the number of bits in the prime number +/// \returns Integer() meeting Maurer's tests for primality CRYPTOPP_DLL Integer CRYPTOPP_API MaurerProvablePrime(RandomNumberGenerator &rng, unsigned int bits); -//! \brief Generates a provable prime -//! \param rng a RandomNumberGenerator to produce keying material -//! \param bits the number of bits in the prime number -//! \returns Integer() meeting Mihailescu's tests for primality -//! \details Mihailescu's methods performs a search using algorithmic progressions. +/// \brief Generates a provable prime +/// \param rng a RandomNumberGenerator to produce keying material +/// \param bits the number of bits in the prime number +/// \returns Integer() meeting Mihailescu's tests for primality +/// \details Mihailescu's methods performs a search using algorithmic progressions. CRYPTOPP_DLL Integer CRYPTOPP_API MihailescuProvablePrime(RandomNumberGenerator &rng, unsigned int bits); -//! \brief Tests whether a number is a small prime -//! \param p a candidate prime to test -//! \returns true if p is a small prime, false otherwise -//! \details Internally, the library maintains a table fo the first 32719 prime numbers -//! in sorted order. IsSmallPrime() searches the table and returns true if p is -//! in the table. +/// \brief Tests whether a number is a small prime +/// \param p a candidate prime to test +/// \returns true if p is a small prime, false otherwise +/// \details Internally, the library maintains a table fo the first 32719 prime numbers +/// in sorted order. IsSmallPrime() searches the table and returns true if p is +/// in the table. CRYPTOPP_DLL bool CRYPTOPP_API IsSmallPrime(const Integer &p); -//! -//! \returns true if p is divisible by some prime less than bound. -//! \details TrialDivision() true if p is divisible by some prime less than bound. bound not be -//! greater than the largest entry in the prime table, which is 32719. +/// +/// \returns true if p is divisible by some prime less than bound. +/// \details TrialDivision() true if p is divisible by some prime less than bound. bound not be +/// greater than the largest entry in the prime table, which is 32719. CRYPTOPP_DLL bool CRYPTOPP_API TrialDivision(const Integer &p, unsigned bound); // returns true if p is NOT divisible by small primes @@ -58,25 +58,25 @@ CRYPTOPP_DLL bool CRYPTOPP_API IsStrongLucasProbablePrime(const Integer &n); // for several rounds with random bases CRYPTOPP_DLL bool CRYPTOPP_API RabinMillerTest(RandomNumberGenerator &rng, const Integer &w, unsigned int rounds); -//! \brief Verifies a prime number -//! \param p a candidate prime to test -//! \returns true if p is a probable prime, false otherwise -//! \details IsPrime() is suitable for testing candidate primes when creating them. Internally, -//! IsPrime() utilizes SmallDivisorsTest(), IsStrongProbablePrime() and IsStrongLucasProbablePrime(). +/// \brief Verifies a prime number +/// \param p a candidate prime to test +/// \returns true if p is a probable prime, false otherwise +/// \details IsPrime() is suitable for testing candidate primes when creating them. Internally, +/// IsPrime() utilizes SmallDivisorsTest(), IsStrongProbablePrime() and IsStrongLucasProbablePrime(). CRYPTOPP_DLL bool CRYPTOPP_API IsPrime(const Integer &p); -//! \brief Verifies a prime number -//! \param rng a RandomNumberGenerator for randomized testing -//! \param p a candidate prime to test -//! \param level the level of thoroughness of testing -//! \returns true if p is a strong probable prime, false otherwise -//! \details VerifyPrime() is suitable for testing candidate primes created by others. Internally, -//! VerifyPrime() utilizes IsPrime() and one-round RabinMillerTest(). If the candiate passes and -//! level is greater than 1, then 10 round RabinMillerTest() primality testing is performed. +/// \brief Verifies a prime number +/// \param rng a RandomNumberGenerator for randomized testing +/// \param p a candidate prime to test +/// \param level the level of thoroughness of testing +/// \returns true if p is a strong probable prime, false otherwise +/// \details VerifyPrime() is suitable for testing candidate primes created by others. Internally, +/// VerifyPrime() utilizes IsPrime() and one-round RabinMillerTest(). If the candiate passes and +/// level is greater than 1, then 10 round RabinMillerTest() primality testing is performed. CRYPTOPP_DLL bool CRYPTOPP_API VerifyPrime(RandomNumberGenerator &rng, const Integer &p, unsigned int level = 1); -//! \class PrimeSelector -//! \brief Application callback to signal suitability of a cabdidate prime +/// \class PrimeSelector +/// \brief Application callback to signal suitability of a cabdidate prime class CRYPTOPP_DLL PrimeSelector { public: @@ -84,16 +84,16 @@ public: virtual bool IsAcceptable(const Integer &candidate) const =0; }; -//! \brief Finds a random prime of special form -//! \param p an Integer reference to receive the prime -//! \param max the maximum value -//! \param equiv the equivalence class based on the parameter mod -//! \param mod the modulus used to reduce the equivalence class -//! \param pSelector pointer to a PrimeSelector function for the application to signal suitability -//! \returns true if and only if FirstPrime() finds a prime and returns the prime through p. If FirstPrime() -//! returns false, then no such prime exists and the value of p is undefined -//! \details FirstPrime() uses a fast sieve to find the first probable prime -//! in {x | p<=x<=max and x%mod==equiv} +/// \brief Finds a random prime of special form +/// \param p an Integer reference to receive the prime +/// \param max the maximum value +/// \param equiv the equivalence class based on the parameter mod +/// \param mod the modulus used to reduce the equivalence class +/// \param pSelector pointer to a PrimeSelector function for the application to signal suitability +/// \returns true if and only if FirstPrime() finds a prime and returns the prime through p. If FirstPrime() +/// returns false, then no such prime exists and the value of p is undefined +/// \details FirstPrime() uses a fast sieve to find the first probable prime +/// in {x | p<=x<=max and x%mod==equiv} CRYPTOPP_DLL bool CRYPTOPP_API FirstPrime(Integer &p, const Integer &max, const Integer &equiv, const Integer &mod, const PrimeSelector *pSelector); CRYPTOPP_DLL unsigned int CRYPTOPP_API PrimeSearchInterval(const Integer &max); @@ -143,54 +143,54 @@ CRYPTOPP_DLL unsigned int CRYPTOPP_API FactoringWorkFactor(unsigned int bitlengt // ******************************************************** -//! \class PrimeAndGenerator -//! \brief Generator of prime numbers of special forms +/// \class PrimeAndGenerator +/// \brief Generator of prime numbers of special forms class CRYPTOPP_DLL PrimeAndGenerator { public: - //! \brief Construct a PrimeAndGenerator + /// \brief Construct a PrimeAndGenerator PrimeAndGenerator() {} - //! \brief Construct a PrimeAndGenerator - //! \param delta +1 or -1 - //! \param rng a RandomNumberGenerator derived class - //! \param pbits the number of bits in the prime p - //! \details PrimeAndGenerator() generates a random prime p of the form 2*q+delta, where delta is 1 or -1 and q is - //! also prime. Internally the constructor calls Generate(delta, rng, pbits, pbits-1). - //! \pre pbits > 5 - //! \warning This PrimeAndGenerator() is slow because primes of this form are harder to find. + /// \brief Construct a PrimeAndGenerator + /// \param delta +1 or -1 + /// \param rng a RandomNumberGenerator derived class + /// \param pbits the number of bits in the prime p + /// \details PrimeAndGenerator() generates a random prime p of the form 2*q+delta, where delta is 1 or -1 and q is + /// also prime. Internally the constructor calls Generate(delta, rng, pbits, pbits-1). + /// \pre pbits > 5 + /// \warning This PrimeAndGenerator() is slow because primes of this form are harder to find. PrimeAndGenerator(signed int delta, RandomNumberGenerator &rng, unsigned int pbits) {Generate(delta, rng, pbits, pbits-1);} - //! \brief Construct a PrimeAndGenerator - //! \param delta +1 or -1 - //! \param rng a RandomNumberGenerator derived class - //! \param pbits the number of bits in the prime p - //! \param qbits the number of bits in the prime q - //! \details PrimeAndGenerator() generates a random prime p of the form 2*r*q+delta, where q is also prime. - //! Internally the constructor calls Generate(delta, rng, pbits, qbits). - //! \pre qbits > 4 && pbits > qbits + /// \brief Construct a PrimeAndGenerator + /// \param delta +1 or -1 + /// \param rng a RandomNumberGenerator derived class + /// \param pbits the number of bits in the prime p + /// \param qbits the number of bits in the prime q + /// \details PrimeAndGenerator() generates a random prime p of the form 2*r*q+delta, where q is also prime. + /// Internally the constructor calls Generate(delta, rng, pbits, qbits). + /// \pre qbits > 4 && pbits > qbits PrimeAndGenerator(signed int delta, RandomNumberGenerator &rng, unsigned int pbits, unsigned qbits) {Generate(delta, rng, pbits, qbits);} - //! \brief Generate a Prime and Generator - //! \param delta +1 or -1 - //! \param rng a RandomNumberGenerator derived class - //! \param pbits the number of bits in the prime p - //! \param qbits the number of bits in the prime q - //! \details Generate() generates a random prime p of the form 2*r*q+delta, where q is also prime. + /// \brief Generate a Prime and Generator + /// \param delta +1 or -1 + /// \param rng a RandomNumberGenerator derived class + /// \param pbits the number of bits in the prime p + /// \param qbits the number of bits in the prime q + /// \details Generate() generates a random prime p of the form 2*r*q+delta, where q is also prime. void Generate(signed int delta, RandomNumberGenerator &rng, unsigned int pbits, unsigned qbits); - //! \brief Retrieve first prime - //! \returns Prime() returns the prime p. + /// \brief Retrieve first prime + /// \returns Prime() returns the prime p. const Integer& Prime() const {return p;} - //! \brief Retrieve second prime - //! \returns SubPrime() returns the prime q. + /// \brief Retrieve second prime + /// \returns SubPrime() returns the prime q. const Integer& SubPrime() const {return q;} - //! \brief Retrieve the generator - //! \returns Generator() returns the the generator g. + /// \brief Retrieve the generator + /// \returns Generator() returns the the generator g. const Integer& Generator() const {return g;} private: diff --git a/network.h b/network.h index 065ea49a..3ea90dee 100644 --- a/network.h +++ b/network.h @@ -50,17 +50,17 @@ private: double GetCurTimeAndCleanUp(); }; -//! a Source class that can pump from a device for a specified amount of time. +/// a Source class that can pump from a device for a specified amount of time. class CRYPTOPP_NO_VTABLE NonblockingSource : public AutoSignaling, public LimitedBandwidth { public: NonblockingSource(BufferedTransformation *attachment) : m_messageEndSent(false) , m_doPumpBlocked(false), m_blockedBySpeedLimit(false) {Detach(attachment);} - //! \name NONBLOCKING SOURCE + /// \name NONBLOCKING SOURCE //@{ - //! pump up to maxSize bytes using at most maxTime milliseconds + /// pump up to maxSize bytes using at most maxTime milliseconds /*! If checkDelimiter is true, pump up to delimiter, which itself is not extracted or pumped. */ size_t GeneralPump2(lword &byteCount, bool blockingOutput=true, unsigned long maxTime=INFINITE_TIME, bool checkDelimiter=false, byte delimiter='\n'); @@ -89,13 +89,13 @@ private: bool m_messageEndSent, m_doPumpBlocked, m_blockedBySpeedLimit; }; -//! Network Receiver +/// Network Receiver class CRYPTOPP_NO_VTABLE NetworkReceiver : public Waitable { public: virtual bool MustWaitToReceive() {return false;} virtual bool MustWaitForResult() {return false;} - //! receive data from network source, returns whether result is immediately available + /// receive data from network source, returns whether result is immediately available virtual bool Receive(byte* buf, size_t bufLen) =0; virtual unsigned int GetReceiveResult() =0; virtual bool EofReceived() const =0; @@ -108,13 +108,13 @@ public: virtual size_t GetMaxBufferSize() const =0; virtual size_t GetCurrentBufferSize() const =0; virtual bool EofPending() const =0; - //! compute the current speed of this sink in bytes per second + /// compute the current speed of this sink in bytes per second virtual float ComputeCurrentSpeed() =0; - //! get the maximum observed speed of this sink in bytes per second + /// get the maximum observed speed of this sink in bytes per second virtual float GetMaxObservedSpeed() const =0; }; -//! a Sink class that queues input and can flush to a device for a specified amount of time. +/// a Sink class that queues input and can flush to a device for a specified amount of time. class CRYPTOPP_NO_VTABLE NonblockingSink : public Sink, public NonblockingSinkInfo, public LimitedBandwidth { public: @@ -122,7 +122,7 @@ public: bool IsolatedFlush(bool hardFlush, bool blocking); - //! flush to device for no more than maxTime milliseconds + /// flush to device for no more than maxTime milliseconds /*! This function will repeatedly attempt to flush data to some device, until the queue is empty, or a total of maxTime milliseconds have elapsed. If maxTime == 0, at least one attempt will be made to flush some data, but @@ -135,7 +135,7 @@ public: lword TimedFlush(unsigned long maxTime, size_t targetSize = 0); virtual void SetMaxBufferSize(size_t maxBufferSize) =0; - //! set a bound which will cause sink to flush if exceeded by GetCurrentBufferSize() + /// set a bound which will cause sink to flush if exceeded by GetCurrentBufferSize() virtual void SetAutoFlushBound(size_t bound) =0; protected: @@ -147,7 +147,7 @@ private: bool m_blockedBySpeedLimit; }; -//! Network Sender +/// Network Sender class CRYPTOPP_NO_VTABLE NetworkSender : public Waitable { public: @@ -160,7 +160,7 @@ public: virtual bool EofSent() {return false;} // implement if MustWaitForEof() == true }; -//! Network Source +/// Network Source class CRYPTOPP_NO_VTABLE NetworkSource : public NonblockingSource { public: @@ -183,7 +183,7 @@ private: bool m_waitingForResult, m_outputBlocked; }; -//! Network Sink +/// Network Sink class CRYPTOPP_NO_VTABLE NetworkSink : public NonblockingSink { public: @@ -204,9 +204,9 @@ public: bool EofPending() const { return m_eofState > EOF_NONE && m_eofState < EOF_DONE; } - //! compute the current speed of this sink in bytes per second + /// compute the current speed of this sink in bytes per second float ComputeCurrentSpeed(); - //! get the maximum observed speed of this sink in bytes per second + /// get the maximum observed speed of this sink in bytes per second float GetMaxObservedSpeed() const; protected: diff --git a/oaep.h b/oaep.h index 1809af43..ec4172b2 100644 --- a/oaep.h +++ b/oaep.h @@ -7,7 +7,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief OAEP padding base class +/// \brief OAEP padding base class class CRYPTOPP_DLL OAEP_Base : public PK_EncryptionMessageEncodingMethod { public: @@ -22,8 +22,8 @@ protected: virtual MaskGeneratingFunction * NewMGF() const =0; }; -//! \brief OAEP padding -//! \sa EME-OAEP, for use with classes derived from TF_ES +/// \brief OAEP padding +/// \sa EME-OAEP, for use with classes derived from TF_ES template class OAEP : public OAEP_Base, public EncryptionStandard { diff --git a/oids.h b/oids.h index c4502a5b..fff82989 100644 --- a/oids.h +++ b/oids.h @@ -1,13 +1,13 @@ // oids.h - originally written and placed in the public domain by Wei Dai -//! \file oids.h -//! \brief ASN.1 object identifiers for algorthms and schemes -//! \details Most OIDs can be found at http://www.oid-info.com/. The Chinese OIDs -//! are assigned in GM/T 0006-2012, Cryptographic Application Identifier Criterion -//! Specification. A reproduction can be found at http://gmssl.org/docs/oid.html. -//! There seems to be some confusion between the text of GmSSL's oid.html web page -//! and the actual OID used in the code. We used the same OIDs that were detailed in -//! http://github.com/guanzhi/GmSSL/blob/master/crypto/objects/objects.txt. +/// \file oids.h +/// \brief ASN.1 object identifiers for algorthms and schemes +/// \details Most OIDs can be found at http://www.oid-info.com/. The Chinese OIDs +/// are assigned in GM/T 0006-2012, Cryptographic Application Identifier Criterion +/// Specification. A reproduction can be found at http://gmssl.org/docs/oid.html. +/// There seems to be some confusion between the text of GmSSL's oid.html web page +/// and the actual OID used in the code. We used the same OIDs that were detailed in +/// http://github.com/guanzhi/GmSSL/blob/master/crypto/objects/objects.txt. #ifndef CRYPTOPP_OIDS_H #define CRYPTOPP_OIDS_H diff --git a/osrng.h b/osrng.h index 0c377a68..d5cf3394 100644 --- a/osrng.h +++ b/osrng.h @@ -1,7 +1,7 @@ // osrng.h - originally written and placed in the public domain by Wei Dai -//! \file osrng.h -//! \brief Classes for access to the operating system's random number generators +/// \file osrng.h +/// \brief Classes for access to the operating system's random number generators #ifndef CRYPTOPP_OSRNG_H #define CRYPTOPP_OSRNG_H @@ -20,26 +20,26 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class OS_RNG_Err -//! \brief Exception thrown when an operating system error is encountered +/// \class OS_RNG_Err +/// \brief Exception thrown when an operating system error is encountered class CRYPTOPP_DLL OS_RNG_Err : public Exception { public: - //! \brief Constructs an OS_RNG_Err - //! \param operation the operation or API call when the error occurs + /// \brief Constructs an OS_RNG_Err + /// \param operation the operation or API call when the error occurs OS_RNG_Err(const std::string &operation); }; #ifdef NONBLOCKING_RNG_AVAILABLE #ifdef CRYPTOPP_WIN32_AVAILABLE -//! \class MicrosoftCryptoProvider -//! \brief Wrapper for Microsoft crypto service provider -//! \sa \def USE_MS_CRYPTOAPI, \def USE_MS_CNGAPI +/// \class MicrosoftCryptoProvider +/// \brief Wrapper for Microsoft crypto service provider +/// \sa \def USE_MS_CRYPTOAPI, \def USE_MS_CNGAPI class CRYPTOPP_DLL MicrosoftCryptoProvider { public: - //! \brief Construct a MicrosoftCryptoProvider + /// \brief Construct a MicrosoftCryptoProvider MicrosoftCryptoProvider(); ~MicrosoftCryptoProvider(); @@ -57,13 +57,13 @@ public: typedef PVOID ProviderHandle; #endif // USE_MS_CRYPTOAPI or USE_MS_CNGAPI - //! \brief Retrieves the provider handle - //! \returns CryptoAPI provider handle - //! \details If USE_MS_CRYPTOAPI is in effect, then CryptAcquireContext() - //! acquires then handle and CryptReleaseContext() releases the handle - //! upon destruction. If USE_MS_CNGAPI is in effect, then - //! BCryptOpenAlgorithmProvider() acquires then handle and - //! BCryptCloseAlgorithmProvider() releases the handle upon destruction. + /// \brief Retrieves the provider handle + /// \returns CryptoAPI provider handle + /// \details If USE_MS_CRYPTOAPI is in effect, then CryptAcquireContext() + /// acquires then handle and CryptReleaseContext() releases the handle + /// upon destruction. If USE_MS_CNGAPI is in effect, then + /// BCryptOpenAlgorithmProvider() acquires then handle and + /// BCryptCloseAlgorithmProvider() releases the handle upon destruction. ProviderHandle GetProviderHandle() const {return m_hProvider;} private: @@ -80,10 +80,10 @@ private: #endif // CRYPTOPP_WIN32_AVAILABLE -//! \class NonblockingRng -//! \brief Wrapper class for /dev/random and /dev/srandom -//! \details Encapsulates CryptoAPI's CryptGenRandom() or CryptoNG's BCryptGenRandom() -//! on Windows, or /dev/urandom on Unix and compatibles. +/// \class NonblockingRng +/// \brief Wrapper class for /dev/random and /dev/srandom +/// \details Encapsulates CryptoAPI's CryptGenRandom() or CryptoNG's BCryptGenRandom() +/// on Windows, or /dev/urandom on Unix and compatibles. class CRYPTOPP_DLL NonblockingRng : public RandomNumberGenerator { public: @@ -91,13 +91,13 @@ public: ~NonblockingRng(); - //! \brief Construct a NonblockingRng + /// \brief Construct a NonblockingRng NonblockingRng(); - //! \brief Generate random array of bytes - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes - //! \details GenerateIntoBufferedTransformation() calls are routed to GenerateBlock(). + /// \brief Generate random array of bytes + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes + /// \details GenerateIntoBufferedTransformation() calls are routed to GenerateBlock(). void GenerateBlock(byte *output, size_t size); protected: @@ -112,13 +112,13 @@ protected: #if defined(BLOCKING_RNG_AVAILABLE) || defined(CRYPTOPP_DOXYGEN_PROCESSING) -//! \class BlockingRng -//! \brief Wrapper class for /dev/random and /dev/srandom -//! \details Encapsulates /dev/random on Linux, OS X and Unix; and /dev/srandom on the BSDs. -//! \note On Linux the /dev/random interface is effectively deprecated. According to the -//! Kernel Crypto developers, /dev/urandom or getrandom(2) should be used instead. Also -//! see [RFC PATCH v12 3/4] Linux Random -//! Number Generator on the kernel-crypto mailing list. +/// \class BlockingRng +/// \brief Wrapper class for /dev/random and /dev/srandom +/// \details Encapsulates /dev/random on Linux, OS X and Unix; and /dev/srandom on the BSDs. +/// \note On Linux the /dev/random interface is effectively deprecated. According to the +/// Kernel Crypto developers, /dev/urandom or getrandom(2) should be used instead. Also +/// see [RFC PATCH v12 3/4] Linux Random +/// Number Generator on the kernel-crypto mailing list. class CRYPTOPP_DLL BlockingRng : public RandomNumberGenerator { public: @@ -126,13 +126,13 @@ public: ~BlockingRng(); - //! \brief Construct a BlockingRng + /// \brief Construct a BlockingRng BlockingRng(); - //! \brief Generate random array of bytes - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes - //! \details GenerateIntoBufferedTransformation() calls are routed to GenerateBlock(). + /// \brief Generate random array of bytes + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes + /// \details GenerateIntoBufferedTransformation() calls are routed to GenerateBlock(). void GenerateBlock(byte *output, size_t size); protected: @@ -141,22 +141,22 @@ protected: #endif -//! OS_GenerateRandomBlock -//! \brief Generate random array of bytes -//! \param blocking specifies whther a bobcking or non-blocking generator should be used -//! \param output the byte buffer -//! \param size the length of the buffer, in bytes -//! \details OS_GenerateRandomBlock() uses the underlying operating system's -//! random number generator. On Windows, CryptGenRandom() is called using NonblockingRng. -//! \details On Unix and compatibles, /dev/urandom is called if blocking is false using -//! NonblockingRng. If blocking is true, then either /dev/randomd or /dev/srandom is used -//! by way of BlockingRng, if available. +/// OS_GenerateRandomBlock +/// \brief Generate random array of bytes +/// \param blocking specifies whther a bobcking or non-blocking generator should be used +/// \param output the byte buffer +/// \param size the length of the buffer, in bytes +/// \details OS_GenerateRandomBlock() uses the underlying operating system's +/// random number generator. On Windows, CryptGenRandom() is called using NonblockingRng. +/// \details On Unix and compatibles, /dev/urandom is called if blocking is false using +/// NonblockingRng. If blocking is true, then either /dev/randomd or /dev/srandom is used +/// by way of BlockingRng, if available. CRYPTOPP_DLL void CRYPTOPP_API OS_GenerateRandomBlock(bool blocking, byte *output, size_t size); -//! \class AutoSeededRandomPool -//! \brief Automatically Seeded Randomness Pool -//! \details This class seeds itself using an operating system provided RNG. -//! AutoSeededRandomPool was suggested by Leonard Janke. +/// \class AutoSeededRandomPool +/// \brief Automatically Seeded Randomness Pool +/// \details This class seeds itself using an operating system provided RNG. +/// AutoSeededRandomPool was suggested by Leonard Janke. class CRYPTOPP_DLL AutoSeededRandomPool : public RandomPool { public: @@ -164,29 +164,29 @@ public: ~AutoSeededRandomPool() {} - //! \brief Construct an AutoSeededRandomPool - //! \param blocking controls seeding with BlockingRng or NonblockingRng - //! \param seedSize the size of the seed, in bytes - //! \details Use blocking to choose seeding with BlockingRng or NonblockingRng. - //! The parameter is ignored if only one of these is available. + /// \brief Construct an AutoSeededRandomPool + /// \param blocking controls seeding with BlockingRng or NonblockingRng + /// \param seedSize the size of the seed, in bytes + /// \details Use blocking to choose seeding with BlockingRng or NonblockingRng. + /// The parameter is ignored if only one of these is available. explicit AutoSeededRandomPool(bool blocking = false, unsigned int seedSize = 32) {Reseed(blocking, seedSize);} - //! \brief Reseed an AutoSeededRandomPool - //! \param blocking controls seeding with BlockingRng or NonblockingRng - //! \param seedSize the size of the seed, in bytes + /// \brief Reseed an AutoSeededRandomPool + /// \param blocking controls seeding with BlockingRng or NonblockingRng + /// \param seedSize the size of the seed, in bytes void Reseed(bool blocking = false, unsigned int seedSize = 32); }; -//! \class AutoSeededX917RNG -//! \tparam BLOCK_CIPHER a block cipher -//! \brief Automatically Seeded X9.17 RNG -//! \details AutoSeededX917RNG is from ANSI X9.17 Appendix C, seeded using an OS provided RNG. -//! If 3-key TripleDES (DES_EDE3) is used, then its a X9.17 conforming generator. If AES is -//! used, then its a X9.31 conforming generator. -//! \details Though ANSI X9 prescribes 3-key TripleDES, the template parameter BLOCK_CIPHER can be any -//! BlockTransformation derived class. -//! \sa X917RNG, DefaultAutoSeededRNG +/// \class AutoSeededX917RNG +/// \tparam BLOCK_CIPHER a block cipher +/// \brief Automatically Seeded X9.17 RNG +/// \details AutoSeededX917RNG is from ANSI X9.17 Appendix C, seeded using an OS provided RNG. +/// If 3-key TripleDES (DES_EDE3) is used, then its a X9.17 conforming generator. If AES is +/// used, then its a X9.31 conforming generator. +/// \details Though ANSI X9 prescribes 3-key TripleDES, the template parameter BLOCK_CIPHER can be any +/// BlockTransformation derived class. +/// \sa X917RNG, DefaultAutoSeededRNG template class AutoSeededX917RNG : public RandomNumberGenerator, public NotCopyable { @@ -195,31 +195,31 @@ public: ~AutoSeededX917RNG() {} - //! \brief Construct an AutoSeededX917RNG - //! \param blocking controls seeding with BlockingRng or NonblockingRng - //! \param autoSeed controls auto seeding of the generator - //! \details Use blocking to choose seeding with BlockingRng or NonblockingRng. - //! The parameter is ignored if only one of these is available. - //! \sa X917RNG + /// \brief Construct an AutoSeededX917RNG + /// \param blocking controls seeding with BlockingRng or NonblockingRng + /// \param autoSeed controls auto seeding of the generator + /// \details Use blocking to choose seeding with BlockingRng or NonblockingRng. + /// The parameter is ignored if only one of these is available. + /// \sa X917RNG explicit AutoSeededX917RNG(bool blocking = false, bool autoSeed = true) {if (autoSeed) Reseed(blocking);} - //! \brief Reseed an AutoSeededX917RNG - //! \param blocking controls seeding with BlockingRng or NonblockingRng - //! \param additionalEntropy additional entropy to add to the generator - //! \param length the size of the additional entropy, in bytes - //! \details Internally, the generator uses SHA256 to extract the entropy from - //! from the seed and then stretch the material for the block cipher's key - //! and initialization vector. + /// \brief Reseed an AutoSeededX917RNG + /// \param blocking controls seeding with BlockingRng or NonblockingRng + /// \param additionalEntropy additional entropy to add to the generator + /// \param length the size of the additional entropy, in bytes + /// \details Internally, the generator uses SHA256 to extract the entropy from + /// from the seed and then stretch the material for the block cipher's key + /// and initialization vector. void Reseed(bool blocking = false, const byte *additionalEntropy = NULLPTR, size_t length = 0); - //! \brief Deterministically reseed an AutoSeededX917RNG for testing - //! \param key the key to use for the deterministic reseeding - //! \param keylength the size of the key, in bytes - //! \param seed the seed to use for the deterministic reseeding - //! \param timeVector a time vector to use for deterministic reseeding - //! \details This is a testing interface for testing purposes, and should \a NOT - //! be used in production. + /// \brief Deterministically reseed an AutoSeededX917RNG for testing + /// \param key the key to use for the deterministic reseeding + /// \param keylength the size of the key, in bytes + /// \param seed the seed to use for the deterministic reseeding + /// \param timeVector a time vector to use for deterministic reseeding + /// \details This is a testing interface for testing purposes, and should \a NOT + /// be used in production. void Reseed(const byte *key, size_t keylength, const byte *seed, const byte *timeVector); bool CanIncorporateEntropy() const {return true;} @@ -262,11 +262,11 @@ void AutoSeededX917RNG::Reseed(bool blocking, const byte *input, s CRYPTOPP_DLL_TEMPLATE_CLASS AutoSeededX917RNG; #if defined(CRYPTOPP_DOXYGEN_PROCESSING) -//! \class DefaultAutoSeededRNG -//! \brief A typedef providing a default generator -//! \details DefaultAutoSeededRNG is a typedef of either AutoSeededX917RNG or AutoSeededRandomPool. -//! If CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined, then DefaultAutoSeededRNG is -//! AutoSeededX917RNG. Otherwise, DefaultAutoSeededRNG is AutoSeededRandomPool. +/// \class DefaultAutoSeededRNG +/// \brief A typedef providing a default generator +/// \details DefaultAutoSeededRNG is a typedef of either AutoSeededX917RNG or AutoSeededRandomPool. +/// If CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined, then DefaultAutoSeededRNG is +/// AutoSeededX917RNG. Otherwise, DefaultAutoSeededRNG is AutoSeededRandomPool. class DefaultAutoSeededRNG {} #else // AutoSeededX917RNG in FIPS mode, otherwise it's AutoSeededRandomPool diff --git a/ossig.h b/ossig.h index 107eabd6..2c172586 100644 --- a/ossig.h +++ b/ossig.h @@ -1,8 +1,8 @@ // ossig.h - written and placed in the public domain by Jeffrey Walton // -//! \file ossig.h -//! \brief Utility class for trapping OS signals. -//! \since Crypto++ 5.6.5 +/// \file ossig.h +/// \brief Utility class for trapping OS signals. +/// \since Crypto++ 5.6.5 #ifndef CRYPTOPP_OS_SIGNAL_H #define CRYPTOPP_OS_SIGNAL_H @@ -19,62 +19,62 @@ NAMESPACE_BEGIN(CryptoPP) #if defined(UNIX_SIGNALS_AVAILABLE) || defined(CRYPTOPP_DOXYGEN_PROCESSING) -//! \brief Signal handler function pointer -//! \details SignalHandlerFn is provided as a stand alone function pointer with external "C" linkage -//! \sa SignalHandler, NullSignalHandler +/// \brief Signal handler function pointer +/// \details SignalHandlerFn is provided as a stand alone function pointer with external "C" linkage +/// \sa SignalHandler, NullSignalHandler extern "C" { typedef void (*SignalHandlerFn) (int); }; -//! \brief Null signal handler function -//! \param unused the signal number -//! \details NullSignalHandler is provided as a stand alone function with external "C" linkage -//! and not a static member function due to the the member function's implicit -//! external "C++" linkage. -//! \sa SignalHandler, SignalHandlerFn +/// \brief Null signal handler function +/// \param unused the signal number +/// \details NullSignalHandler is provided as a stand alone function with external "C" linkage +/// and not a static member function due to the the member function's implicit +/// external "C++" linkage. +/// \sa SignalHandler, SignalHandlerFn extern "C" { inline void NullSignalHandler(int unused) {CRYPTOPP_UNUSED(unused);} }; -//! Signal handler for Linux and Unix compatibles -//! \tparam S Signal number -//! \tparam O Flag indicating exsting handler should be overwriiten -//! \details SignalHandler() can be used to install a signal handler with the signature -//! void handler_fn(int). If SignalHandlerFn is not NULL, then -//! the sigaction is set to the function and the sigaction flags is set to the flags. -//! If SignalHandlerFn is NULL, then a default handler is installed -//! using sigaction flags set to 0. The default handler only returns from the call. -//! \details Upon destruction the previous signal handler is restored if the former signal handler -//! was replaced. -//! \details On Cygwin systems using Newlib, you should define _XOPEN_SOURCE=700 or -//! _GNU_SOURCE; or use -std=gnu++03, -std=gnu++11, or similar. If -//! you compile with -std=c++03, -std=c++11 or similar, then define -//! _XOPEN_SOURCE=700. -//! \warning Do not use SignalHandler in a code block that uses setjmp or longjmp -//! because the destructor may not run. -//! \since Crypto++ 5.6.5 -//! \sa NullSignalHandler, SignalHandlerFn, \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT", DebugTrapHandler +/// Signal handler for Linux and Unix compatibles +/// \tparam S Signal number +/// \tparam O Flag indicating exsting handler should be overwriiten +/// \details SignalHandler() can be used to install a signal handler with the signature +/// void handler_fn(int). If SignalHandlerFn is not NULL, then +/// the sigaction is set to the function and the sigaction flags is set to the flags. +/// If SignalHandlerFn is NULL, then a default handler is installed +/// using sigaction flags set to 0. The default handler only returns from the call. +/// \details Upon destruction the previous signal handler is restored if the former signal handler +/// was replaced. +/// \details On Cygwin systems using Newlib, you should define _XOPEN_SOURCE=700 or +/// _GNU_SOURCE; or use -std=gnu++03, -std=gnu++11, or similar. If +/// you compile with -std=c++03, -std=c++11 or similar, then define +/// _XOPEN_SOURCE=700. +/// \warning Do not use SignalHandler in a code block that uses setjmp or longjmp +/// because the destructor may not run. +/// \since Crypto++ 5.6.5 +/// \sa NullSignalHandler, SignalHandlerFn, \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT", DebugTrapHandler template struct SignalHandler { - //! \brief Construct a signal handler - //! \param pfn Pointer to a signal handler function - //! \param flags Flags to use with the signal handler - //! \details SignalHandler() installs a signal handler with the signature - //! void handler_fn(int). If SignalHandlerFn is not NULL, then - //! the sigaction is set to the function and the sigaction flags is set to the flags. - //! If SignalHandlerFn is NULL, then a default handler is installed - //! using sigaction flags set to 0. The default handler only returns from the call. - //! \details Upon destruction the previous signal handler is restored if the former signal handler - //! was overwritten. - //! \details On Cygwin systems using Newlib, you should define _XOPEN_SOURCE=700 or - //! _GNU_SOURCE; or use -std=gnu++03, -std=gnu++11, or similar. If - //! you compile with -std=c++03, -std=c++11 or similar, then define - //! _XOPEN_SOURCE=700. - //! \warning Do not use SignalHandler in a code block that uses setjmp or longjmp - //! because the destructor may not run. setjmp is why cpu.cpp does not use SignalHandler - //! during CPU feature testing. - //! \since Crypto++ 5.6.5 + /// \brief Construct a signal handler + /// \param pfn Pointer to a signal handler function + /// \param flags Flags to use with the signal handler + /// \details SignalHandler() installs a signal handler with the signature + /// void handler_fn(int). If SignalHandlerFn is not NULL, then + /// the sigaction is set to the function and the sigaction flags is set to the flags. + /// If SignalHandlerFn is NULL, then a default handler is installed + /// using sigaction flags set to 0. The default handler only returns from the call. + /// \details Upon destruction the previous signal handler is restored if the former signal handler + /// was overwritten. + /// \details On Cygwin systems using Newlib, you should define _XOPEN_SOURCE=700 or + /// _GNU_SOURCE; or use -std=gnu++03, -std=gnu++11, or similar. If + /// you compile with -std=c++03, -std=c++11 or similar, then define + /// _XOPEN_SOURCE=700. + /// \warning Do not use SignalHandler in a code block that uses setjmp or longjmp + /// because the destructor may not run. setjmp is why cpu.cpp does not use SignalHandler + /// during CPU feature testing. + /// \since Crypto++ 5.6.5 SignalHandler(SignalHandlerFn pfn = NULLPTR, int flags = 0) : m_installed(false) { // http://pubs.opengroup.org/onlinepubs/007908799/xsh/sigaction.html diff --git a/padlkrng.h b/padlkrng.h index 541ae223..10cd602a 100644 --- a/padlkrng.h +++ b/padlkrng.h @@ -1,10 +1,10 @@ // via-rng.h - written and placed in public domain by Jeffrey Walton -//! \file padlkrng.h -//! \brief Classes for VIA Padlock RNG -//! \since Crypto++ 6.0 -//! \sa VIA -//! Padlock on the Crypto++ wiki +/// \file padlkrng.h +/// \brief Classes for VIA Padlock RNG +/// \since Crypto++ 6.0 +/// \sa VIA +/// Padlock on the Crypto++ wiki #ifndef CRYPTOPP_PADLOCK_RNG_H #define CRYPTOPP_PADLOCK_RNG_H @@ -14,9 +14,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Exception thrown when a PadlockRNG generator encounters -//! a generator related error. -//! \since Crypto++ 6.0 +/// \brief Exception thrown when a PadlockRNG generator encounters +/// a generator related error. +/// \since Crypto++ 6.0 class PadlockRNG_Err : public Exception { public: @@ -26,27 +26,27 @@ public: : Exception(OTHER_ERROR, component + ": " + message) {} }; -//! \brief Hardware generated random numbers using VIA XSTORE -//! \details Some VIA processors provide a Security Engine called Padlock. The Padlock -//! Security Engine provides AES, SHA and a RNG. The PadlockRNG class provides access -//! to the RNG. -//! \details The VIA generator uses an 8 byte FIFO buffer for random numbers. The -//! generator can be configured to discard bits from the buffer to resist analysis. -//! The divisor controls the number of bytes discarded. The formula for -//! the discard amount is 2**divisor - 1. When divisor=0 no bits -//! are discarded and the entire 8 byte buffer is read. If divisor=3 then -//! 7 bytes are discarded and 1 byte is read. TheVIA SDK samples use divisor=1. -//! \details Cryptography Research, Inc (CRI) audited the Padlock Security Engine -//! in 2003. CRI provided recommendations to operate the generator for secure and -//! non-secure applications. Additionally, the Programmers Guide and SDK provided a -//! different configuration in the sample code. -//! \details You can operate the generator according to CRI recommendations by setting -//! divisor, reading one word (or partial word) at a time from the FIFO, and -//! then inspecting the MSR after each read. -//! \details The audit report with recommendations is available on the Crypto++ wiki -//! at VIA Padlock. -//! \sa MaurerRandomnessTest() for random bit generators -//! \since Crypto++ 6.0 +/// \brief Hardware generated random numbers using VIA XSTORE +/// \details Some VIA processors provide a Security Engine called Padlock. The Padlock +/// Security Engine provides AES, SHA and a RNG. The PadlockRNG class provides access +/// to the RNG. +/// \details The VIA generator uses an 8 byte FIFO buffer for random numbers. The +/// generator can be configured to discard bits from the buffer to resist analysis. +/// The divisor controls the number of bytes discarded. The formula for +/// the discard amount is 2**divisor - 1. When divisor=0 no bits +/// are discarded and the entire 8 byte buffer is read. If divisor=3 then +/// 7 bytes are discarded and 1 byte is read. TheVIA SDK samples use divisor=1. +/// \details Cryptography Research, Inc (CRI) audited the Padlock Security Engine +/// in 2003. CRI provided recommendations to operate the generator for secure and +/// non-secure applications. Additionally, the Programmers Guide and SDK provided a +/// different configuration in the sample code. +/// \details You can operate the generator according to CRI recommendations by setting +/// divisor, reading one word (or partial word) at a time from the FIFO, and +/// then inspecting the MSR after each read. +/// \details The audit report with recommendations is available on the Crypto++ wiki +/// at VIA Padlock. +/// \sa MaurerRandomnessTest() for random bit generators +/// \since Crypto++ 6.0 class PadlockRNG : public RandomNumberGenerator { public: @@ -54,51 +54,51 @@ public: virtual ~PadlockRNG() {} - //! \brief Construct a PadlockRNG generator - //! \param divisor the XSTORE divisor - //! \details Some VIA processors provide a Security Engine called Padlock. The Padlock - //! Security Engine provides AES, SHA and a RNG. The PadlockRNG class provides access - //! to the RNG. - //! \details The VIA generator uses an 8 byte FIFO buffer for random numbers. The - //! generator can be configured to discard bits from the buffer to resist analysis. - //! The divisor controls the number of bytes discarded. The formula for - //! the discard amount is 2**divisor - 1. When divisor=0 no bits - //! are discarded and the entire 8 byte buffer is read. If divisor=3 then - //! 7 bytes are discarded and 1 byte is read. VIA SDK samples use divisor=1. - //! \details Cryptography Research, Inc (CRI) audited the Padlock Security Engine - //! in 2003. CRI provided recommendations to operate the generator for secure and - //! non-secure applications. Additionally, the Programmers SDK provided a different - //! configuration in the sample code. - //! \details The audit report with recommendations is available on the Crypto++ wiki - //! at VIA Padlock. - //! \sa SetDivisor, GetDivisor + /// \brief Construct a PadlockRNG generator + /// \param divisor the XSTORE divisor + /// \details Some VIA processors provide a Security Engine called Padlock. The Padlock + /// Security Engine provides AES, SHA and a RNG. The PadlockRNG class provides access + /// to the RNG. + /// \details The VIA generator uses an 8 byte FIFO buffer for random numbers. The + /// generator can be configured to discard bits from the buffer to resist analysis. + /// The divisor controls the number of bytes discarded. The formula for + /// the discard amount is 2**divisor - 1. When divisor=0 no bits + /// are discarded and the entire 8 byte buffer is read. If divisor=3 then + /// 7 bytes are discarded and 1 byte is read. VIA SDK samples use divisor=1. + /// \details Cryptography Research, Inc (CRI) audited the Padlock Security Engine + /// in 2003. CRI provided recommendations to operate the generator for secure and + /// non-secure applications. Additionally, the Programmers SDK provided a different + /// configuration in the sample code. + /// \details The audit report with recommendations is available on the Crypto++ wiki + /// at VIA Padlock. + /// \sa SetDivisor, GetDivisor PadlockRNG(word32 divisor=1); - //! \brief Generate random array of bytes - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes + /// \brief Generate random array of bytes + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes virtual void GenerateBlock(byte *output, size_t size); - //! \brief Generate and discard n bytes - //! \param n the number of bytes to generate and discard - //! \details the Padlock generator discards words, not bytes. If n is - //! not a multiple of a 32-bit word, then it is rounded up to - //! that size. + /// \brief Generate and discard n bytes + /// \param n the number of bytes to generate and discard + /// \details the Padlock generator discards words, not bytes. If n is + /// not a multiple of a 32-bit word, then it is rounded up to + /// that size. virtual void DiscardBytes(size_t n); - //! \brief Update RNG state with additional unpredictable values - //! \param input unused - //! \param length unused - //! \details The operation is a nop for this generator. + /// \brief Update RNG state with additional unpredictable values + /// \param input unused + /// \param length unused + /// \details The operation is a nop for this generator. virtual void IncorporateEntropy(const byte *input, size_t length) { // Override to avoid the base class' throw. CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(length); } - //! \brief Set the XSTORE divisor - //! \param divisor the XSTORE divisor - //! \returns the old XSTORE divisor + /// \brief Set the XSTORE divisor + /// \param divisor the XSTORE divisor + /// \returns the old XSTORE divisor word32 SetDivisor(word32 divisor) { word32 old = m_divisor; @@ -106,15 +106,15 @@ public: return old; } - //! \brief Get the XSTORE divisor - //! \returns the current XSTORE divisor + /// \brief Get the XSTORE divisor + /// \returns the current XSTORE divisor word32 GetDivisor() const { return m_divisor; } - //! \brief Get the MSR for the last operation - //! \returns the MSR for the last read operation + /// \brief Get the MSR for the last operation + /// \returns the MSR for the last read operation word32 GetMSR() const { return m_msr; diff --git a/panama.h b/panama.h index 505de98a..2482062d 100644 --- a/panama.h +++ b/panama.h @@ -1,7 +1,7 @@ // panama.h - originally written and placed in the public domain by Wei Dai -//! \file panama.h -//! \brief Classes for Panama hash and stream cipher +/// \file panama.h +/// \brief Classes for Panama hash and stream cipher #ifndef CRYPTOPP_PANAMA_H #define CRYPTOPP_PANAMA_H @@ -33,9 +33,9 @@ protected: }; namespace Weak { -//! \class PanamaHash -//! \brief Panama hash -//! \sa Panama Hash +/// \class PanamaHash +/// \brief Panama hash +/// \sa Panama Hash template class PanamaHash : protected Panama, public AlgorithmImpl, PanamaHash > { @@ -54,8 +54,8 @@ protected: }; } -//! \class HermeticHashFunctionMAC -//! \brief MAC construction using a hermetic hash function +/// \class HermeticHashFunctionMAC +/// \brief MAC construction using a hermetic hash function template class HermeticHashFunctionMAC : public AlgorithmImpl > >, T_Info> { @@ -111,8 +111,8 @@ protected: }; namespace Weak { -//! \class PanamaMAC -//! \brief Panama message authentication code +/// \class PanamaMAC +/// \brief Panama message authentication code template class PanamaMAC : public HermeticHashFunctionMAC > { @@ -123,16 +123,16 @@ public: }; } -//! \class PanamaCipherInfo -//! \brief Panama stream cipher information +/// \class PanamaCipherInfo +/// \brief Panama stream cipher information template struct PanamaCipherInfo : public FixedKeyLength<32, SimpleKeyingInterface::UNIQUE_IV, 32> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return B::ToEnum() == BIG_ENDIAN_ORDER ? "Panama-BE" : "Panama-LE";} }; -//! \class PanamaCipherPolicy -//! \brief Panama stream cipher operation +/// \class PanamaCipherPolicy +/// \brief Panama stream cipher operation template class PanamaCipherPolicy : public AdditiveCipherConcretePolicy, public PanamaCipherInfo, @@ -148,9 +148,9 @@ protected: FixedSizeSecBlock m_key; }; -//! \class PanamaCipher -//! \brief Panama stream cipher -//! \sa Panama Stream Cipher +/// \class PanamaCipher +/// \brief Panama stream cipher +/// \sa Panama Stream Cipher template struct PanamaCipher : public PanamaCipherInfo, public SymmetricCipherDocumentation { diff --git a/pch.h b/pch.h index 2c77fd52..ae544c4c 100644 --- a/pch.h +++ b/pch.h @@ -1,7 +1,7 @@ // pch.h - originally written and placed in the public domain by Wei Dai -//! \headerfile pch.h -//! \brief Precompiled header file +/// \headerfile pch.h +/// \brief Precompiled header file #ifndef CRYPTOPP_PCH_H #define CRYPTOPP_PCH_H diff --git a/pkcspad.h b/pkcspad.h index 7471d2fd..bc92bfe2 100644 --- a/pkcspad.h +++ b/pkcspad.h @@ -1,8 +1,8 @@ // pkcspad.h - originally written and placed in the public domain by Wei Dai -//! \file pkcspad.h -//! \brief Classes for PKCS padding schemes -//! \details PKCS#1 v1.5, v2.0 and P1363a allow MD2, MD5, SHA1, SHA224, SHA256, SHA384, SHA512, Tiger and RipeMd-160 to be instantiated. +/// \file pkcspad.h +/// \brief Classes for PKCS padding schemes +/// \details PKCS#1 v1.5, v2.0 and P1363a allow MD2, MD5, SHA1, SHA224, SHA256, SHA384, SHA512, Tiger and RipeMd-160 to be instantiated. #ifndef CRYPTOPP_PKCSPAD_H #define CRYPTOPP_PKCSPAD_H @@ -16,9 +16,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class PKCS_EncryptionPaddingScheme -//! \brief PKCS#1 v1.5 Encryption Padding Scheme -//! \sa EME-PKCS1-v1_5 +/// \class PKCS_EncryptionPaddingScheme +/// \brief PKCS#1 v1.5 Encryption Padding Scheme +/// \sa EME-PKCS1-v1_5 class PKCS_EncryptionPaddingScheme : public PK_EncryptionMessageEncodingMethod { public: @@ -29,8 +29,8 @@ public: DecodingResult Unpad(const byte *padded, size_t paddedLength, byte *raw, const NameValuePairs ¶meters) const; }; -//! \class PKCS_DigestDecoration -//! \brief PKCS#1 decoration data structure +/// \class PKCS_DigestDecoration +/// \brief PKCS#1 decoration data structure template class PKCS_DigestDecoration { public: @@ -78,9 +78,9 @@ template const byte PKCS_DigestDecoration::decoration[1] = {0x00}; #endif -//! \class PKCS1v15_SignatureMessageEncodingMethod -//! \brief PKCS#1 v1.5 Signature Encoding Scheme -//! \sa EMSA-PKCS1-v1_5 +/// \class PKCS1v15_SignatureMessageEncodingMethod +/// \brief PKCS#1 v1.5 Signature Encoding Scheme +/// \sa EMSA-PKCS1-v1_5 class CRYPTOPP_DLL PKCS1v15_SignatureMessageEncodingMethod : public PK_DeterministicSignatureMessageEncodingMethod { public: @@ -106,8 +106,8 @@ public: }; }; -//! \brief PKCS #1 version 1.5, for use with RSAES and RSASS -//! \dontinclude pkcspad.h +/// \brief PKCS #1 version 1.5, for use with RSAES and RSASS +/// \dontinclude pkcspad.h struct PKCS1v15 : public SignatureStandard, public EncryptionStandard { diff --git a/poly1305.h b/poly1305.h index 8e2617d0..006a91bf 100644 --- a/poly1305.h +++ b/poly1305.h @@ -1,45 +1,45 @@ // poly1305.h - written and placed in the public domain by Jeffrey Walton and Jean-Pierre Munch // Based on Andy Polyakov's Base-2^26 scalar multiplication implementation for OpenSSL. -//! \file poly1305.h -//! \brief Classes for Poly1305 message authentication code -//! \details Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide -//! variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length -//! message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce. -//! \details Each message must use a unique security context, which means either the key or nonce -//! must be changed after each message. It can be accomplished in one of two ways. First, you -//! can create a new Poly1305 object with a key and nonce each time its needed. -//! 
  SecByteBlock key(32), nonce(16);
-//!   prng.GenerateBlock(key, key.size());
-//!   prng.GenerateBlock(nonce, nonce.size());
-//!
-//!   Poly1305 poly1305(key, key.size(), nonce, nonce.size());
-//!   poly1305.Update(...);
-//!   poly1305.Final(...);
-//! -//! \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce -//! for each message. The second and subsequent nonces can be generated directly using a -//! RandomNumberGenerator() derived class; or it can be generated using GetNextIV(). -//! 
  SecByteBlock key(32), nonce(16);
-//!   prng.GenerateBlock(key, key.size());
-//!   prng.GenerateBlock(nonce, nonce.size());
-//!
-//!   // First message
-//!   Poly1305 poly1305(key, key.size());
-//!   poly1305.Resynchronize(nonce);
-//!   poly1305.Update(...);
-//!   poly1305.Final(...);
-//!
-//!   // Second message
-//!   poly1305.GetNextIV(prng, nonce);
-//!   poly1305.Resynchronize(nonce);
-//!   poly1305.Update(...);
-//!   poly1305.Final(...);
-//!   ...
-//! \sa Daniel J. Bernstein The Poly1305-AES -//! Message-Authentication Code (20050329) and Andy Polyakov Poly1305 Revised -//! \since Crypto++ 6.0 +/// \file poly1305.h +/// \brief Classes for Poly1305 message authentication code +/// \details Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide +/// variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length +/// message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce. +/// \details Each message must use a unique security context, which means either the key or nonce +/// must be changed after each message. It can be accomplished in one of two ways. First, you +/// can create a new Poly1305 object with a key and nonce each time its needed. +/// 
  SecByteBlock key(32), nonce(16);
+///   prng.GenerateBlock(key, key.size());
+///   prng.GenerateBlock(nonce, nonce.size());
+///
+///   Poly1305 poly1305(key, key.size(), nonce, nonce.size());
+///   poly1305.Update(...);
+///   poly1305.Final(...);
+/// +/// \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce +/// for each message. The second and subsequent nonces can be generated directly using a +/// RandomNumberGenerator() derived class; or it can be generated using GetNextIV(). +/// 
  SecByteBlock key(32), nonce(16);
+///   prng.GenerateBlock(key, key.size());
+///   prng.GenerateBlock(nonce, nonce.size());
+///
+///   // First message
+///   Poly1305 poly1305(key, key.size());
+///   poly1305.Resynchronize(nonce);
+///   poly1305.Update(...);
+///   poly1305.Final(...);
+///
+///   // Second message
+///   poly1305.GetNextIV(prng, nonce);
+///   poly1305.Resynchronize(nonce);
+///   poly1305.Update(...);
+///   poly1305.Final(...);
+///   ...
+/// \sa Daniel J. Bernstein The Poly1305-AES +/// Message-Authentication Code (20050329) and Andy Polyakov Poly1305 Revised +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_POLY1305_H #define CRYPTOPP_POLY1305_H @@ -52,10 +52,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Poly1305_Base -//! \brief Poly1305 message authentication code base class -//! \tparam T class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize -//! \since Crypto++ 6.0 +/// \class Poly1305_Base +/// \brief Poly1305 message authentication code base class +/// \tparam T class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize +/// \since Crypto++ 6.0 template class CRYPTOPP_NO_VTABLE Poly1305_Base : public FixedKeyLength<32, SimpleKeyingInterface::UNIQUE_IV, 16>, public MessageAuthenticationCode { @@ -100,66 +100,66 @@ protected: bool m_used; }; -//! \class Poly1305 -//! \brief Poly1305 message authentication code -//! \tparam T class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize -//! \details Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide -//! variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length -//! message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce. -//! \details Each message must use a unique security context, which means either the key or nonce -//! must be changed after each message. It can be accomplished in one of two ways. First, you -//! can create a new Poly1305 object with a key and nonce each time its needed. -//! 
  SecByteBlock key(32), nonce(16);
-//!   prng.GenerateBlock(key, key.size());
-//!   prng.GenerateBlock(nonce, nonce.size());
-//!
-//!   Poly1305 poly1305(key, key.size(), nonce, nonce.size());
-//!   poly1305.Update(...);
-//!   poly1305.Final(...);
-//! -//! \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce -//! for each message. The second and subsequent nonces can be generated directly using a -//! RandomNumberGenerator() derived class; or it can be generated using GetNextIV(). -//! 
  SecByteBlock key(32), nonce(16);
-//!   prng.GenerateBlock(key, key.size());
-//!   prng.GenerateBlock(nonce, nonce.size());
-//!
-//!   // First message
-//!   Poly1305 poly1305(key, key.size());
-//!   poly1305.Resynchronize(nonce);
-//!   poly1305.Update(...);
-//!   poly1305.Final(...);
-//!
-//!   // Second message
-//!   poly1305.GetNextIV(prng, nonce);
-//!   poly1305.Resynchronize(nonce);
-//!   poly1305.Update(...);
-//!   poly1305.Final(...);
-//!   ...
-//! \warning The Poly1305 class does not enforce a fresh nonce for each message. The source code -//! will assert in debug builds to alert of nonce reuse. No action is taken in release builds. -//! \sa Daniel J. Bernstein The Poly1305-AES -//! Message-Authentication Code (20050329) and Andy Polyakov Poly1305 Revised -//! \since Crypto++ 6.0 +/// \class Poly1305 +/// \brief Poly1305 message authentication code +/// \tparam T class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize +/// \details Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide +/// variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length +/// message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce. +/// \details Each message must use a unique security context, which means either the key or nonce +/// must be changed after each message. It can be accomplished in one of two ways. First, you +/// can create a new Poly1305 object with a key and nonce each time its needed. +/// 
  SecByteBlock key(32), nonce(16);
+///   prng.GenerateBlock(key, key.size());
+///   prng.GenerateBlock(nonce, nonce.size());
+///
+///   Poly1305 poly1305(key, key.size(), nonce, nonce.size());
+///   poly1305.Update(...);
+///   poly1305.Final(...);
+/// +/// \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce +/// for each message. The second and subsequent nonces can be generated directly using a +/// RandomNumberGenerator() derived class; or it can be generated using GetNextIV(). +/// 
  SecByteBlock key(32), nonce(16);
+///   prng.GenerateBlock(key, key.size());
+///   prng.GenerateBlock(nonce, nonce.size());
+///
+///   // First message
+///   Poly1305 poly1305(key, key.size());
+///   poly1305.Resynchronize(nonce);
+///   poly1305.Update(...);
+///   poly1305.Final(...);
+///
+///   // Second message
+///   poly1305.GetNextIV(prng, nonce);
+///   poly1305.Resynchronize(nonce);
+///   poly1305.Update(...);
+///   poly1305.Final(...);
+///   ...
+/// \warning The Poly1305 class does not enforce a fresh nonce for each message. The source code +/// will assert in debug builds to alert of nonce reuse. No action is taken in release builds. +/// \sa Daniel J. Bernstein The Poly1305-AES +/// Message-Authentication Code (20050329) and Andy Polyakov Poly1305 Revised +/// \since Crypto++ 6.0 template class Poly1305 : public MessageAuthenticationCodeFinal > { public: CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=Poly1305_Base::DEFAULT_KEYLENGTH) - //! \brief Construct a Poly1305 + /// \brief Construct a Poly1305 Poly1305() {} - //! \brief Construct a Poly1305 - //! \param key a byte array used to key the cipher - //! \param keyLength the size of the byte array, in bytes - //! \param nonce a byte array used to key the cipher - //! \param nonceLength the size of the byte array, in bytes - //! \details key is the 32-byte key composed of the 16-byte AES key and the 16 additional key - //! bytes used for r. - //! \details Each message requires a unique security context. You can use GetNextIV() and - //! Resynchronize() to set a new nonce under a key for a message. + /// \brief Construct a Poly1305 + /// \param key a byte array used to key the cipher + /// \param keyLength the size of the byte array, in bytes + /// \param nonce a byte array used to key the cipher + /// \param nonceLength the size of the byte array, in bytes + /// \details key is the 32-byte key composed of the 16-byte AES key and the 16 additional key + /// bytes used for r. + /// \details Each message requires a unique security context. You can use GetNextIV() and + /// Resynchronize() to set a new nonce under a key for a message. Poly1305(const byte *key, size_t keyLength=DEFAULT_KEYLENGTH, const byte *nonce=NULLPTR, size_t nonceLength=0) {this->SetKey(key, keyLength, MakeParameters(Name::IV(), ConstByteArrayParameter(nonce, nonceLength)));} }; diff --git a/polynomi.h b/polynomi.h index 2b904204..96dd238a 100644 --- a/polynomi.h +++ b/polynomi.h @@ -1,8 +1,8 @@ // polynomi.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile polynomi.h -//! \brief Classes for polynomial basis and operations +/// \file +/// \headerfile polynomi.h +/// \brief Classes for polynomial basis and operations #ifndef CRYPTOPP_POLYNOMI_H @@ -20,21 +20,21 @@ NAMESPACE_BEGIN(CryptoPP) -//! represents single-variable polynomials over arbitrary rings +/// represents single-variable polynomials over arbitrary rings /*! \nosubgrouping */ template class PolynomialOver { public: - //! \name ENUMS, EXCEPTIONS, and TYPEDEFS + /// \name ENUMS, EXCEPTIONS, and TYPEDEFS //@{ - //! division by zero exception + /// division by zero exception class DivideByZero : public Exception { public: DivideByZero() : Exception(OTHER_ERROR, "PolynomialOver: division by zero") {} }; - //! specify the distribution for randomization functions + /// specify the distribution for randomization functions class RandomizationParameter { public: @@ -51,74 +51,74 @@ public: typedef typename T::Element CoefficientType; //@} - //! \name CREATORS + /// \name CREATORS //@{ - //! creates the zero polynomial + /// creates the zero polynomial PolynomialOver() {} - //! + /// PolynomialOver(const Ring &ring, unsigned int count) : m_coefficients((size_t)count, ring.Identity()) {} - //! copy constructor + /// copy constructor PolynomialOver(const PolynomialOver &t) : m_coefficients(t.m_coefficients.size()) {*this = t;} - //! construct constant polynomial + /// construct constant polynomial PolynomialOver(const CoefficientType &element) : m_coefficients(1, element) {} - //! construct polynomial with specified coefficients, starting from coefficient of x^0 + /// construct polynomial with specified coefficients, starting from coefficient of x^0 template PolynomialOver(Iterator begin, Iterator end) : m_coefficients(begin, end) {} - //! convert from string + /// convert from string PolynomialOver(const char *str, const Ring &ring) {FromStr(str, ring);} - //! convert from big-endian byte array + /// convert from big-endian byte array PolynomialOver(const byte *encodedPolynomialOver, unsigned int byteCount); - //! convert from Basic Encoding Rules encoded byte array + /// convert from Basic Encoding Rules encoded byte array explicit PolynomialOver(const byte *BEREncodedPolynomialOver); - //! convert from BER encoded byte array stored in a BufferedTransformation object + /// convert from BER encoded byte array stored in a BufferedTransformation object explicit PolynomialOver(BufferedTransformation &bt); - //! create a random PolynomialOver + /// create a random PolynomialOver PolynomialOver(RandomNumberGenerator &rng, const RandomizationParameter ¶meter, const Ring &ring) {Randomize(rng, parameter, ring);} //@} - //! \name ACCESSORS + /// \name ACCESSORS //@{ - //! the zero polynomial will return a degree of -1 + /// the zero polynomial will return a degree of -1 int Degree(const Ring &ring) const {return int(CoefficientCount(ring))-1;} - //! + /// unsigned int CoefficientCount(const Ring &ring) const; - //! return coefficient for x^i + /// return coefficient for x^i CoefficientType GetCoefficient(unsigned int i, const Ring &ring) const; //@} - //! \name MANIPULATORS + /// \name MANIPULATORS //@{ - //! + /// PolynomialOver& operator=(const PolynomialOver& t); - //! + /// void Randomize(RandomNumberGenerator &rng, const RandomizationParameter ¶meter, const Ring &ring); - //! set the coefficient for x^i to value + /// set the coefficient for x^i to value void SetCoefficient(unsigned int i, const CoefficientType &value, const Ring &ring); - //! + /// void Negate(const Ring &ring); - //! + /// void swap(PolynomialOver &t); //@} - //! \name BASIC ARITHMETIC ON POLYNOMIALS + /// \name BASIC ARITHMETIC ON POLYNOMIALS //@{ bool Equals(const PolynomialOver &t, const Ring &ring) const; bool IsZero(const Ring &ring) const {return CoefficientCount(ring)==0;} @@ -136,9 +136,9 @@ public: PolynomialOver& Accumulate(const PolynomialOver& t, const Ring &ring); PolynomialOver& Reduce(const PolynomialOver& t, const Ring &ring); - //! + /// PolynomialOver Doubled(const Ring &ring) const {return Plus(*this, ring);} - //! + /// PolynomialOver Squared(const Ring &ring) const {return Times(*this, ring);} CoefficientType EvaluateAt(const CoefficientType &x, const Ring &ring) const; @@ -146,11 +146,11 @@ public: PolynomialOver& ShiftLeft(unsigned int n, const Ring &ring); PolynomialOver& ShiftRight(unsigned int n, const Ring &ring); - //! calculate r and q such that (a == d*q + r) && (0 <= degree of r < degree of d) + /// calculate r and q such that (a == d*q + r) && (0 <= degree of r < degree of d) static void Divide(PolynomialOver &r, PolynomialOver &q, const PolynomialOver &a, const PolynomialOver &d, const Ring &ring); //@} - //! \name INPUT/OUTPUT + /// \name INPUT/OUTPUT //@{ std::istream& Input(std::istream &in, const Ring &ring); std::ostream& Output(std::ostream &out, const Ring &ring) const; @@ -162,7 +162,7 @@ private: std::vector m_coefficients; }; -//! Polynomials over a fixed ring +/// Polynomials over a fixed ring /*! Having a fixed ring allows overloaded operators */ template class PolynomialOverFixedRing : private PolynomialOver { @@ -175,129 +175,129 @@ public: typedef typename B::DivideByZero DivideByZero; typedef typename B::RandomizationParameter RandomizationParameter; - //! \name CREATORS + /// \name CREATORS //@{ - //! creates the zero polynomial + /// creates the zero polynomial PolynomialOverFixedRing(unsigned int count = 0) : B(ms_fixedRing, count) {} - //! copy constructor + /// copy constructor PolynomialOverFixedRing(const ThisType &t) : B(t) {} explicit PolynomialOverFixedRing(const B &t) : B(t) {} - //! construct constant polynomial + /// construct constant polynomial PolynomialOverFixedRing(const CoefficientType &element) : B(element) {} - //! construct polynomial with specified coefficients, starting from coefficient of x^0 + /// construct polynomial with specified coefficients, starting from coefficient of x^0 template PolynomialOverFixedRing(Iterator first, Iterator last) : B(first, last) {} - //! convert from string + /// convert from string explicit PolynomialOverFixedRing(const char *str) : B(str, ms_fixedRing) {} - //! convert from big-endian byte array + /// convert from big-endian byte array PolynomialOverFixedRing(const byte *encodedPoly, unsigned int byteCount) : B(encodedPoly, byteCount) {} - //! convert from Basic Encoding Rules encoded byte array + /// convert from Basic Encoding Rules encoded byte array explicit PolynomialOverFixedRing(const byte *BEREncodedPoly) : B(BEREncodedPoly) {} - //! convert from BER encoded byte array stored in a BufferedTransformation object + /// convert from BER encoded byte array stored in a BufferedTransformation object explicit PolynomialOverFixedRing(BufferedTransformation &bt) : B(bt) {} - //! create a random PolynomialOverFixedRing + /// create a random PolynomialOverFixedRing PolynomialOverFixedRing(RandomNumberGenerator &rng, const RandomizationParameter ¶meter) : B(rng, parameter, ms_fixedRing) {} static const ThisType &Zero(); static const ThisType &One(); //@} - //! \name ACCESSORS + /// \name ACCESSORS //@{ - //! the zero polynomial will return a degree of -1 + /// the zero polynomial will return a degree of -1 int Degree() const {return B::Degree(ms_fixedRing);} - //! degree + 1 + /// degree + 1 unsigned int CoefficientCount() const {return B::CoefficientCount(ms_fixedRing);} - //! return coefficient for x^i + /// return coefficient for x^i CoefficientType GetCoefficient(unsigned int i) const {return B::GetCoefficient(i, ms_fixedRing);} - //! return coefficient for x^i + /// return coefficient for x^i CoefficientType operator[](unsigned int i) const {return B::GetCoefficient(i, ms_fixedRing);} //@} - //! \name MANIPULATORS + /// \name MANIPULATORS //@{ - //! + /// ThisType& operator=(const ThisType& t) {B::operator=(t); return *this;} - //! + /// ThisType& operator+=(const ThisType& t) {Accumulate(t, ms_fixedRing); return *this;} - //! + /// ThisType& operator-=(const ThisType& t) {Reduce(t, ms_fixedRing); return *this;} - //! + /// ThisType& operator*=(const ThisType& t) {return *this = *this*t;} - //! + /// ThisType& operator/=(const ThisType& t) {return *this = *this/t;} - //! + /// ThisType& operator%=(const ThisType& t) {return *this = *this%t;} - //! + /// ThisType& operator<<=(unsigned int n) {ShiftLeft(n, ms_fixedRing); return *this;} - //! + /// ThisType& operator>>=(unsigned int n) {ShiftRight(n, ms_fixedRing); return *this;} - //! set the coefficient for x^i to value + /// set the coefficient for x^i to value void SetCoefficient(unsigned int i, const CoefficientType &value) {B::SetCoefficient(i, value, ms_fixedRing);} - //! + /// void Randomize(RandomNumberGenerator &rng, const RandomizationParameter ¶meter) {B::Randomize(rng, parameter, ms_fixedRing);} - //! + /// void Negate() {B::Negate(ms_fixedRing);} void swap(ThisType &t) {B::swap(t);} //@} - //! \name UNARY OPERATORS + /// \name UNARY OPERATORS //@{ - //! + /// bool operator!() const {return CoefficientCount()==0;} - //! + /// ThisType operator+() const {return *this;} - //! + /// ThisType operator-() const {return ThisType(Inverse(ms_fixedRing));} //@} - //! \name BINARY OPERATORS + /// \name BINARY OPERATORS //@{ - //! + /// friend ThisType operator>>(ThisType a, unsigned int n) {return ThisType(a>>=n);} - //! + /// friend ThisType operator<<(ThisType a, unsigned int n) {return ThisType(a<<=n);} //@} - //! \name OTHER ARITHMETIC FUNCTIONS + /// \name OTHER ARITHMETIC FUNCTIONS //@{ - //! + /// ThisType MultiplicativeInverse() const {return ThisType(B::MultiplicativeInverse(ms_fixedRing));} - //! + /// bool IsUnit() const {return B::IsUnit(ms_fixedRing);} - //! + /// ThisType Doubled() const {return ThisType(B::Doubled(ms_fixedRing));} - //! + /// ThisType Squared() const {return ThisType(B::Squared(ms_fixedRing));} CoefficientType EvaluateAt(const CoefficientType &x) const {return B::EvaluateAt(x, ms_fixedRing);} - //! calculate r and q such that (a == d*q + r) && (0 <= r < abs(d)) + /// calculate r and q such that (a == d*q + r) && (0 <= r < abs(d)) static void Divide(ThisType &r, ThisType &q, const ThisType &a, const ThisType &d) {B::Divide(r, q, a, d, ms_fixedRing);} //@} - //! \name INPUT/OUTPUT + /// \name INPUT/OUTPUT //@{ - //! + /// friend std::istream& operator>>(std::istream& in, ThisType &a) {return a.Input(in, ms_fixedRing);} - //! + /// friend std::ostream& operator<<(std::ostream& out, const ThisType &a) {return a.Output(out, ms_fixedRing);} //@} @@ -314,7 +314,7 @@ private: static const Ring ms_fixedRing; }; -//! Ring of polynomials over another ring +/// Ring of polynomials over another ring template class RingOfPolynomialsOver : public AbstractEuclideanDomain > { public: @@ -404,49 +404,49 @@ void PrepareBulkPolynomialInterpolationAt(const Ring &ring, Element *v, const El template Element BulkPolynomialInterpolateAt(const Ring &ring, const Element y[], const Element v[], unsigned int n); -//! +/// template inline bool operator==(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return a.Equals(b, a.ms_fixedRing);} -//! +/// template inline bool operator!=(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return !(a==b);} -//! +/// template inline bool operator> (const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return a.Degree() > b.Degree();} -//! +/// template inline bool operator>=(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return a.Degree() >= b.Degree();} -//! +/// template inline bool operator< (const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return a.Degree() < b.Degree();} -//! +/// template inline bool operator<=(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return a.Degree() <= b.Degree();} -//! +/// template inline CryptoPP::PolynomialOverFixedRing operator+(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return CryptoPP::PolynomialOverFixedRing(a.Plus(b, a.ms_fixedRing));} -//! +/// template inline CryptoPP::PolynomialOverFixedRing operator-(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return CryptoPP::PolynomialOverFixedRing(a.Minus(b, a.ms_fixedRing));} -//! +/// template inline CryptoPP::PolynomialOverFixedRing operator*(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return CryptoPP::PolynomialOverFixedRing(a.Times(b, a.ms_fixedRing));} -//! +/// template inline CryptoPP::PolynomialOverFixedRing operator/(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return CryptoPP::PolynomialOverFixedRing(a.DividedBy(b, a.ms_fixedRing));} -//! +/// template inline CryptoPP::PolynomialOverFixedRing operator%(const CryptoPP::PolynomialOverFixedRing &a, const CryptoPP::PolynomialOverFixedRing &b) {return CryptoPP::PolynomialOverFixedRing(a.Modulo(b, a.ms_fixedRing));} diff --git a/ppc-crypto.h b/ppc-crypto.h index 5bfd7dd1..14d258f6 100644 --- a/ppc-crypto.h +++ b/ppc-crypto.h @@ -1,17 +1,17 @@ // ppc-crypto.h - written and placed in public domain by Jeffrey Walton -//! \file ppc-crypto.h -//! \brief Support functions for PowerPC and Power8 vector operations -//! \details This header provides an agnostic interface into GCC and -//! IBM XL C/C++ compilers modulo their different built-in functions -//! for accessing vector intructions. -//! \details The abstractions are necesssary to support back to GCC 4.8. -//! GCC 4.8 and 4.9 are still popular, and they are the default -//! compiler for GCC112, GCC118 and others on the compile farm. Older -//! IBM XL C/C++ compilers also experience it due to lack of -//! vec_xl_be support on some platforms. Modern compilers -//! provide best support and don't need many of the little hacks below. -//! \since Crypto++ 6.0 +/// \file ppc-crypto.h +/// \brief Support functions for PowerPC and Power8 vector operations +/// \details This header provides an agnostic interface into GCC and +/// IBM XL C/C++ compilers modulo their different built-in functions +/// for accessing vector intructions. +/// \details The abstractions are necesssary to support back to GCC 4.8. +/// GCC 4.8 and 4.9 are still popular, and they are the default +/// compiler for GCC112, GCC118 and others on the compile farm. Older +/// IBM XL C/C++ compilers also experience it due to lack of +/// vec_xl_be support on some platforms. Modern compilers +/// provide best support and don't need many of the little hacks below. +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_PPC_CRYPTO_H #define CRYPTOPP_PPC_CRYPTO_H @@ -41,19 +41,19 @@ typedef uint64x2_p8 VectorType; #endif #if defined(CRYPTOPP_DOXYGEN_PROCESSING) -//! \brief Default vector typedef -//! \details IBM XL C/C++ provides equally good support for all vector types, -//! including uint8x16_p8. GCC provides good support for -//! uint64x2_p8. VectorType is typedef'd accordingly to -//! minimize casting to and from buit-in function calls. +/// \brief Default vector typedef +/// \details IBM XL C/C++ provides equally good support for all vector types, +/// including uint8x16_p8. GCC provides good support for +/// uint64x2_p8. VectorType is typedef'd accordingly to +/// minimize casting to and from buit-in function calls. # define VectorType ... #endif -//! \brief Reverse a 16-byte array -//! \param src the byte array -//! \details ReverseByteArrayLE reverses a 16-byte array on a little endian -//! system. It does nothing on a big endian system. -//! \since Crypto++ 6.0 +/// \brief Reverse a 16-byte array +/// \param src the byte array +/// \details ReverseByteArrayLE reverses a 16-byte array on a little endian +/// system. It does nothing on a big endian system. +/// \since Crypto++ 6.0 inline void ReverseByteArrayLE(byte src[16]) { #if defined(CRYPTOPP_XLC_VERSION) && defined(CRYPTOPP_LITTLE_ENDIAN) @@ -65,12 +65,12 @@ inline void ReverseByteArrayLE(byte src[16]) #endif } -//! \brief Reverse a vector -//! \tparam T vector type -//! \param src the vector -//! \details Reverse() endian swaps the bytes in a vector -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Reverse a vector +/// \tparam T vector type +/// \param src the vector +/// \details Reverse() endian swaps the bytes in a vector +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 template inline T Reverse(const T& src) { @@ -79,13 +79,13 @@ inline T Reverse(const T& src) return vec_perm(src, zero, mask); } -//! \brief Loads a vector from a byte array -//! \param src the byte array -//! \details Loads a vector in big endian format from a byte array. -//! VectorLoadBE will swap endianess on little endian systems. -//! \note VectorLoadBE() does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Loads a vector from a byte array +/// \param src the byte array +/// \details Loads a vector in big endian format from a byte array. +/// VectorLoadBE will swap endianess on little endian systems. +/// \note VectorLoadBE() does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 inline VectorType VectorLoadBE(const uint8_t src[16]) { #if defined(CRYPTOPP_XLC_VERSION) @@ -99,14 +99,14 @@ inline VectorType VectorLoadBE(const uint8_t src[16]) #endif } -//! \brief Loads a vector from a byte array -//! \param src the byte array -//! \param off offset into the src byte array -//! \details Loads a vector in big endian format from a byte array. -//! VectorLoadBE will swap endianess on little endian systems. -//! \note VectorLoadBE does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Loads a vector from a byte array +/// \param src the byte array +/// \param off offset into the src byte array +/// \details Loads a vector in big endian format from a byte array. +/// VectorLoadBE will swap endianess on little endian systems. +/// \note VectorLoadBE does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 inline VectorType VectorLoadBE(int off, const uint8_t src[16]) { #if defined(CRYPTOPP_XLC_VERSION) @@ -122,38 +122,38 @@ inline VectorType VectorLoadBE(int off, const uint8_t src[16]) ////////////////////////////////////////////////////////////////// -//! \brief Loads a vector from a byte array -//! \param src the byte array -//! \details Loads a vector in big endian format from a byte array. -//! VectorLoad will swap endianess on little endian systems. -//! \note VectorLoad does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Loads a vector from a byte array +/// \param src the byte array +/// \details Loads a vector in big endian format from a byte array. +/// VectorLoad will swap endianess on little endian systems. +/// \note VectorLoad does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 inline VectorType VectorLoad(const byte src[16]) { return (VectorType)VectorLoadBE((uint8_t*)src); } -//! \brief Loads a vector from a byte array -//! \param src the byte array -//! \param off offset into the src byte array -//! \details Loads a vector in big endian format from a byte array. -//! VectorLoad will swap endianess on little endian systems. -//! \note VectorLoad does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Loads a vector from a byte array +/// \param src the byte array +/// \param off offset into the src byte array +/// \details Loads a vector in big endian format from a byte array. +/// VectorLoad will swap endianess on little endian systems. +/// \note VectorLoad does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 inline VectorType VectorLoad(int off, const byte src[16]) { return (VectorType)VectorLoadBE(off, (uint8_t*)src); } -//! \brief Loads a vector from a byte array -//! \param src the byte array -//! \details Loads a vector from a byte array. -//! VectorLoadKey does not swap endianess on little endian systems. -//! \note VectorLoadKey does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Loads a vector from a byte array +/// \param src the byte array +/// \details Loads a vector from a byte array. +/// VectorLoadKey does not swap endianess on little endian systems. +/// \note VectorLoadKey does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 inline VectorType VectorLoadKey(const byte src[16]) { #if defined(CRYPTOPP_XLC_VERSION) @@ -163,13 +163,13 @@ inline VectorType VectorLoadKey(const byte src[16]) #endif } -//! \brief Loads a vector from a 32-bit word array -//! \param src the 32-bit word array -//! \details Loads a vector from a 32-bit word array. -//! VectorLoadKey does not swap endianess on little endian systems. -//! \note VectorLoadKey does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Loads a vector from a 32-bit word array +/// \param src the 32-bit word array +/// \details Loads a vector from a 32-bit word array. +/// VectorLoadKey does not swap endianess on little endian systems. +/// \note VectorLoadKey does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 inline VectorType VectorLoadKey(const word32 src[4]) { #if defined(CRYPTOPP_XLC_VERSION) @@ -179,14 +179,14 @@ inline VectorType VectorLoadKey(const word32 src[4]) #endif } -//! \brief Loads a vector from a byte array -//! \param src the byte array -//! \param off offset into the src byte array -//! \details Loads a vector from a byte array. -//! VectorLoadKey does not swap endianess on little endian systems. -//! \note VectorLoadKey does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Loads a vector from a byte array +/// \param src the byte array +/// \param off offset into the src byte array +/// \details Loads a vector from a byte array. +/// VectorLoadKey does not swap endianess on little endian systems. +/// \note VectorLoadKey does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 inline VectorType VectorLoadKey(int off, const byte src[16]) { #if defined(CRYPTOPP_XLC_VERSION) @@ -196,15 +196,15 @@ inline VectorType VectorLoadKey(int off, const byte src[16]) #endif } -//! \brief Stores a vector to a byte array -//! \tparam T vector type -//! \param src the vector -//! \param dest the byte array -//! \details Stores a vector in big endian format to a byte array. -//! VectorStoreBE will swap endianess on little endian systems. -//! \note VectorStoreBE does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Stores a vector to a byte array +/// \tparam T vector type +/// \param src the vector +/// \param dest the byte array +/// \details Stores a vector in big endian format to a byte array. +/// VectorStoreBE will swap endianess on little endian systems. +/// \note VectorStoreBE does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 template inline void VectorStoreBE(const T& src, uint8_t dest[16]) { @@ -218,16 +218,16 @@ inline void VectorStoreBE(const T& src, uint8_t dest[16]) # endif #endif } -//! \brief Stores a vector to a byte array -//! \tparam T vector type -//! \param src the vector -//! \param off offset into the dest byte array -//! \param dest the byte array -//! \details Stores a vector in big endian format to a byte array. -//! VectorStoreBE will swap endianess on little endian systems. -//! \note VectorStoreBE does not require an aligned array. -//! \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() -//! \since Crypto++ 6.0 +/// \brief Stores a vector to a byte array +/// \tparam T vector type +/// \param src the vector +/// \param off offset into the dest byte array +/// \param dest the byte array +/// \details Stores a vector in big endian format to a byte array. +/// VectorStoreBE will swap endianess on little endian systems. +/// \note VectorStoreBE does not require an aligned array. +/// \sa Reverse(), VectorLoadBE(), VectorLoad(), VectorLoadKey() +/// \since Crypto++ 6.0 template inline void VectorStoreBE(const T& src, int off, uint8_t dest[16]) { @@ -242,14 +242,14 @@ inline void VectorStoreBE(const T& src, int off, uint8_t dest[16]) #endif } -//! \brief Stores a vector to a byte array -//! \tparam T vector type -//! \param src the vector -//! \param dest the byte array -//! \details Stores a vector in big endian format to a byte array. -//! VectorStore will swap endianess on little endian systems. -//! \note VectorStore does not require an aligned array. -//! \since Crypto++ 6.0 +/// \brief Stores a vector to a byte array +/// \tparam T vector type +/// \param src the vector +/// \param dest the byte array +/// \details Stores a vector in big endian format to a byte array. +/// VectorStore will swap endianess on little endian systems. +/// \note VectorStore does not require an aligned array. +/// \since Crypto++ 6.0 template inline void VectorStore(const T& src, byte dest[16]) { @@ -265,15 +265,15 @@ inline void VectorStore(const T& src, byte dest[16]) #endif } -//! \brief Stores a vector to a byte array -//! \tparam T vector type -//! \param src the vector -//! \param off offset into the dest byte array -//! \param dest the byte array -//! \details Stores a vector in big endian format to a byte array. -//! VectorStore will swap endianess on little endian systems. -//! \note VectorStore does not require an aligned array. -//! \since Crypto++ 6.0 +/// \brief Stores a vector to a byte array +/// \tparam T vector type +/// \param src the vector +/// \param off offset into the dest byte array +/// \param dest the byte array +/// \details Stores a vector in big endian format to a byte array. +/// VectorStore will swap endianess on little endian systems. +/// \note VectorStore does not require an aligned array. +/// \since Crypto++ 6.0 template inline void VectorStore(const T& src, int off, byte dest[16]) { @@ -289,73 +289,73 @@ inline void VectorStore(const T& src, int off, byte dest[16]) #endif } -//! \brief Permutes two vectors -//! \tparam T1 vector type -//! \tparam T2 vector type -//! \param vec1 the first vector -//! \param vec2 the second vector -//! \param mask vector mask -//! \details VectorPermute returns a new vector from vec1 and vec2 -//! based on mask. mask is an uint8x16_p8 type vector. The return -//! vector is the same type as vec1. -//! \since Crypto++ 6.0 +/// \brief Permutes two vectors +/// \tparam T1 vector type +/// \tparam T2 vector type +/// \param vec1 the first vector +/// \param vec2 the second vector +/// \param mask vector mask +/// \details VectorPermute returns a new vector from vec1 and vec2 +/// based on mask. mask is an uint8x16_p8 type vector. The return +/// vector is the same type as vec1. +/// \since Crypto++ 6.0 template inline T1 VectorPermute(const T1& vec1, const T1& vec2, const T2& mask) { return (T1)vec_perm(vec1, vec2, (uint8x16_p8)mask); } -//! \brief XOR two vectors -//! \tparam T1 vector type -//! \tparam T2 vector type -//! \param vec1 the first vector -//! \param vec2 the second vector -//! \details VectorXor returns a new vector from vec1 and vec2. The return -//! vector is the same type as vec1. -//! \since Crypto++ 6.0 +/// \brief XOR two vectors +/// \tparam T1 vector type +/// \tparam T2 vector type +/// \param vec1 the first vector +/// \param vec2 the second vector +/// \details VectorXor returns a new vector from vec1 and vec2. The return +/// vector is the same type as vec1. +/// \since Crypto++ 6.0 template inline T1 VectorXor(const T1& vec1, const T2& vec2) { return (T1)vec_xor(vec1, (T1)vec2); } -//! \brief Add two vector -//! \tparam T1 vector type -//! \tparam T2 vector type -//! \param vec1 the first vector -//! \param vec2 the second vector -//! \details VectorAdd returns a new vector from vec1 and vec2. -//! vec2 is cast to the same type as vec1. The return vector -//! is the same type as vec1. -//! \since Crypto++ 6.0 +/// \brief Add two vector +/// \tparam T1 vector type +/// \tparam T2 vector type +/// \param vec1 the first vector +/// \param vec2 the second vector +/// \details VectorAdd returns a new vector from vec1 and vec2. +/// vec2 is cast to the same type as vec1. The return vector +/// is the same type as vec1. +/// \since Crypto++ 6.0 template inline T1 VectorAdd(const T1& vec1, const T2& vec2) { return (T1)vec_add(vec1, (T1)vec2); } -//! \brief Shift two vectors left -//! \tparam C shift byte count -//! \tparam T1 vector type -//! \tparam T2 vector type -//! \param vec1 the first vector -//! \param vec2 the second vector -//! \details VectorShiftLeft() concatenates vec1 and vec2 and returns a -//! new vector after shifting the concatenation by the specified number -//! of bytes. Both vec1 and vec2 are cast to uint8x16_p8. The return -//! vector is the same type as vec1. -//! \details On big endian machines VectorShiftLeft() is vec_sld(a, b, -//! c). On little endian machines VectorShiftLeft() is translated to -//! vec_sld(b, a, 16-c). You should always call the function as -//! if on a big endian machine as shown below. -//! 
-//!    uint8x16_p8 r0 = {0};
-//!    uint8x16_p8 r1 = VectorLoad(ptr);
-//!    uint8x16_p8 r5 = VectorShiftLeft<12>(r0, r1);
-//!
-//! \sa Is vec_sld -//! endian sensitive? on Stack Overflow -//! \since Crypto++ 6.0 +/// \brief Shift two vectors left +/// \tparam C shift byte count +/// \tparam T1 vector type +/// \tparam T2 vector type +/// \param vec1 the first vector +/// \param vec2 the second vector +/// \details VectorShiftLeft() concatenates vec1 and vec2 and returns a +/// new vector after shifting the concatenation by the specified number +/// of bytes. Both vec1 and vec2 are cast to uint8x16_p8. The return +/// vector is the same type as vec1. +/// \details On big endian machines VectorShiftLeft() is vec_sld(a, b, +/// c). On little endian machines VectorShiftLeft() is translated to +/// vec_sld(b, a, 16-c). You should always call the function as +/// if on a big endian machine as shown below. +/// 
+///    uint8x16_p8 r0 = {0};
+///    uint8x16_p8 r1 = VectorLoad(ptr);
+///    uint8x16_p8 r5 = VectorShiftLeft<12>(r0, r1);
+///
+/// \sa Is vec_sld +/// endian sensitive? on Stack Overflow +/// \since Crypto++ 6.0 template inline T1 VectorShiftLeft(const T1& vec1, const T2& vec2) { @@ -366,14 +366,14 @@ inline T1 VectorShiftLeft(const T1& vec1, const T2& vec2) #endif } -//! \brief One round of AES encryption -//! \tparam T1 vector type -//! \tparam T2 vector type -//! \param state the state vector -//! \param key the subkey vector -//! \details VectorEncrypt performs one round of AES encryption of state -//! using subkey key. The return vector is the same type as vec1. -//! \since Crypto++ 6.0 +/// \brief One round of AES encryption +/// \tparam T1 vector type +/// \tparam T2 vector type +/// \param state the state vector +/// \param key the subkey vector +/// \details VectorEncrypt performs one round of AES encryption of state +/// using subkey key. The return vector is the same type as vec1. +/// \since Crypto++ 6.0 template inline T1 VectorEncrypt(const T1& state, const T2& key) { @@ -386,14 +386,14 @@ inline T1 VectorEncrypt(const T1& state, const T2& key) #endif } -//! \brief Final round of AES encryption -//! \tparam T1 vector type -//! \tparam T2 vector type -//! \param state the state vector -//! \param key the subkey vector -//! \details VectorEncryptLast performs the final round of AES encryption -//! of state using subkey key. The return vector is the same type as vec1. -//! \since Crypto++ 6.0 +/// \brief Final round of AES encryption +/// \tparam T1 vector type +/// \tparam T2 vector type +/// \param state the state vector +/// \param key the subkey vector +/// \details VectorEncryptLast performs the final round of AES encryption +/// of state using subkey key. The return vector is the same type as vec1. +/// \since Crypto++ 6.0 template inline T1 VectorEncryptLast(const T1& state, const T2& key) { @@ -406,14 +406,14 @@ inline T1 VectorEncryptLast(const T1& state, const T2& key) #endif } -//! \brief One round of AES decryption -//! \tparam T1 vector type -//! \tparam T2 vector type -//! \param state the state vector -//! \param key the subkey vector -//! \details VectorDecrypt performs one round of AES decryption of state -//! using subkey key. The return vector is the same type as vec1. -//! \since Crypto++ 6.0 +/// \brief One round of AES decryption +/// \tparam T1 vector type +/// \tparam T2 vector type +/// \param state the state vector +/// \param key the subkey vector +/// \details VectorDecrypt performs one round of AES decryption of state +/// using subkey key. The return vector is the same type as vec1. +/// \since Crypto++ 6.0 template inline T1 VectorDecrypt(const T1& state, const T2& key) { @@ -426,14 +426,14 @@ inline T1 VectorDecrypt(const T1& state, const T2& key) #endif } -//! \brief Final round of AES decryption -//! \tparam T1 vector type -//! \tparam T2 vector type -//! \param state the state vector -//! \param key the subkey vector -//! \details VectorDecryptLast performs the final round of AES decryption -//! of state using subkey key. The return vector is the same type as vec1. -//! \since Crypto++ 6.0 +/// \brief Final round of AES decryption +/// \tparam T1 vector type +/// \tparam T2 vector type +/// \param state the state vector +/// \param key the subkey vector +/// \details VectorDecryptLast performs the final round of AES decryption +/// of state using subkey key. The return vector is the same type as vec1. +/// \since Crypto++ 6.0 template inline T1 VectorDecryptLast(const T1& state, const T2& key) { @@ -446,14 +446,14 @@ inline T1 VectorDecryptLast(const T1& state, const T2& key) #endif } -//! \brief SHA256 Sigma functions -//! \tparam func function -//! \tparam subfunc sub-function -//! \tparam T vector type -//! \param vec the block to transform -//! \details VectorSHA256 selects sigma0, sigma1, Sigma0, Sigma1 based on -//! func and subfunc. The return vector is the same type as vec. -//! \since Crypto++ 6.0 +/// \brief SHA256 Sigma functions +/// \tparam func function +/// \tparam subfunc sub-function +/// \tparam T vector type +/// \param vec the block to transform +/// \details VectorSHA256 selects sigma0, sigma1, Sigma0, Sigma1 based on +/// func and subfunc. The return vector is the same type as vec. +/// \since Crypto++ 6.0 template inline T VectorSHA256(const T& vec) { @@ -466,14 +466,14 @@ inline T VectorSHA256(const T& vec) #endif } -//! \brief SHA512 Sigma functions -//! \tparam func function -//! \tparam subfunc sub-function -//! \tparam T vector type -//! \param vec the block to transform -//! \details VectorSHA512 selects sigma0, sigma1, Sigma0, Sigma1 based on -//! func and subfunc. The return vector is the same type as vec. -//! \since Crypto++ 6.0 +/// \brief SHA512 Sigma functions +/// \tparam func function +/// \tparam subfunc sub-function +/// \tparam T vector type +/// \param vec the block to transform +/// \details VectorSHA512 selects sigma0, sigma1, Sigma0, Sigma1 based on +/// func and subfunc. The return vector is the same type as vec. +/// \since Crypto++ 6.0 template inline T VectorSHA512(const T& vec) { diff --git a/pssr.h b/pssr.h index c7b2031a..377900ee 100644 --- a/pssr.h +++ b/pssr.h @@ -1,7 +1,7 @@ // pssr.h - originally written and placed in the public domain by Wei Dai -//! \file pssr.h -//! \brief Classes for probablistic signature schemes +/// \file pssr.h +/// \brief Classes for probablistic signature schemes #ifndef CRYPTOPP_PSSR_H #define CRYPTOPP_PSSR_H @@ -16,7 +16,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief PSSR Message Encoding Method interface +/// \brief PSSR Message Encoding Method interface class CRYPTOPP_DLL PSSR_MEM_Base : public PK_RecoverableSignatureMessageEncodingMethod { public: @@ -44,27 +44,27 @@ private: byte *recoverableMessage) const; }; -//! \brief PSSR Message Encoding Method with Hash Identifier -//! \tparam USE_HASH_ID flag indicating whether the HashId is used +/// \brief PSSR Message Encoding Method with Hash Identifier +/// \tparam USE_HASH_ID flag indicating whether the HashId is used template class PSSR_MEM_BaseWithHashId; -//! \brief PSSR Message Encoding Method with Hash Identifier -//! \details If USE_HASH_ID is true, then EMSA2HashIdLookup is used for the base class +/// \brief PSSR Message Encoding Method with Hash Identifier +/// \details If USE_HASH_ID is true, then EMSA2HashIdLookup is used for the base class template<> class PSSR_MEM_BaseWithHashId : public EMSA2HashIdLookup {}; -//! \brief PSSR Message Encoding Method without Hash Identifier -//! \details If USE_HASH_ID is false, then PSSR_MEM_Base is used for the base class +/// \brief PSSR Message Encoding Method without Hash Identifier +/// \details If USE_HASH_ID is false, then PSSR_MEM_Base is used for the base class template<> class PSSR_MEM_BaseWithHashId : public PSSR_MEM_Base {}; -//! \brief PSSR Message Encoding Method -//! \tparam ALLOW_RECOVERY flag indicating whether the scheme provides message recovery -//! \tparam MGF mask generation function -//! \tparam SALT_LEN length of the salt -//! \tparam MIN_PAD_LEN minimum length of the pad -//! \tparam USE_HASH_ID flag indicating whether the HashId is used -//! \details If ALLOW_RECOVERY is true, the the signature scheme provides message recovery. If -//! ALLOW_RECOVERY is false, the the signature scheme is appendix, and the message must be -//! provided during verification. +/// \brief PSSR Message Encoding Method +/// \tparam ALLOW_RECOVERY flag indicating whether the scheme provides message recovery +/// \tparam MGF mask generation function +/// \tparam SALT_LEN length of the salt +/// \tparam MIN_PAD_LEN minimum length of the pad +/// \tparam USE_HASH_ID flag indicating whether the HashId is used +/// \details If ALLOW_RECOVERY is true, the the signature scheme provides message recovery. If +/// ALLOW_RECOVERY is false, the the signature scheme is appendix, and the message must be +/// provided during verification. template class PSSR_MEM : public PSSR_MEM_BaseWithHashId { @@ -77,17 +77,17 @@ public: static std::string CRYPTOPP_API StaticAlgorithmName() {return std::string(ALLOW_RECOVERY ? "PSSR-" : "PSS-") + MGF::StaticAlgorithmName();} }; -//! \brief Probabilistic Signature Scheme with Recovery -//! \details Signature Schemes with Recovery encode the message with the signature. -//! \sa PSSR-MGF1 +/// \brief Probabilistic Signature Scheme with Recovery +/// \details Signature Schemes with Recovery encode the message with the signature. +/// \sa PSSR-MGF1 struct PSSR : public SignatureStandard { typedef PSSR_MEM SignatureMessageEncodingMethod; }; -//! \brief Probabilistic Signature Scheme with Appendix -//! \details Signature Schemes with Appendix require the message to be provided during verification. -//! \sa PSS-MGF1 +/// \brief Probabilistic Signature Scheme with Appendix +/// \details Signature Schemes with Appendix require the message to be provided during verification. +/// \sa PSS-MGF1 struct PSS : public SignatureStandard { typedef PSSR_MEM SignatureMessageEncodingMethod; diff --git a/pubkey.h b/pubkey.h index d90c2ff5..0f7f8b55 100644 --- a/pubkey.h +++ b/pubkey.h @@ -1,35 +1,35 @@ // pubkey.h - originally written and placed in the public domain by Wei Dai -//! \file pubkey.h -//! \brief This file contains helper classes/functions for implementing public key algorithms. -//! \details The class hierachies in this header file tend to look like this: -//! -//! 
-//!                   x1
-//!                  +--+
-//!                  |  |
-//!                 y1  z1
-//!                  |  |
-//!             x2  x2
-//!                  |  |
-//!                 y2  z2
-//!                  |  |
-//!             x3  x3
-//!                  |  |
-//!                 y3  z3
-//!
-//! -//!
    -//!
  • x1, y1, z1 are abstract interface classes defined in cryptlib.h -//!
  • x2, y2, z2 are implementations of the interfaces using "abstract policies", which -//! are pure virtual functions that should return interfaces to interchangeable algorithms. -//! These classes have Base suffixes. -//!
  • x3, y3, z3 hold actual algorithms and implement those virtual functions. -//! These classes have Impl suffixes. -//!
-//! -//! \details The TF_ prefix means an implementation using trapdoor functions on integers. -//! \details The DL_ prefix means an implementation using group operations in groups where discrete log is hard. +/// \file pubkey.h +/// \brief This file contains helper classes/functions for implementing public key algorithms. +/// \details The class hierachies in this header file tend to look like this: +/// +/// 
+///                   x1
+///                  +--+
+///                  |  |
+///                 y1  z1
+///                  |  |
+///             x2  x2
+///                  |  |
+///                 y2  z2
+///                  |  |
+///             x3  x3
+///                  |  |
+///                 y3  z3
+///
+/// +///
    +///
  • x1, y1, z1 are abstract interface classes defined in cryptlib.h +///
  • x2, y2, z2 are implementations of the interfaces using "abstract policies", which +/// are pure virtual functions that should return interfaces to interchangeable algorithms. +/// These classes have Base suffixes. +///
  • x3, y3, z3 hold actual algorithms and implement those virtual functions. +/// These classes have Impl suffixes. +///
+/// +/// \details The TF_ prefix means an implementation using trapdoor functions on integers. +/// \details The DL_ prefix means an implementation using group operations in groups where discrete log is hard. #ifndef CRYPTOPP_PUBKEY_H #define CRYPTOPP_PUBKEY_H @@ -60,157 +60,157 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class TrapdoorFunctionBounds -//! \brief Provides range for plaintext and ciphertext lengths -//! \details A trapdoor function is a function that is easy to compute in one direction, -//! but difficult to compute in the opposite direction without special knowledge. -//! The special knowledge is usually the private key. -//! \details Trapdoor functions only handle messages of a limited length or size. -//! MaxPreimage is the plaintext's maximum length, and MaxImage is the -//! ciphertext's maximum length. -//! \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), -//! RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() +/// \class TrapdoorFunctionBounds +/// \brief Provides range for plaintext and ciphertext lengths +/// \details A trapdoor function is a function that is easy to compute in one direction, +/// but difficult to compute in the opposite direction without special knowledge. +/// The special knowledge is usually the private key. +/// \details Trapdoor functions only handle messages of a limited length or size. +/// MaxPreimage is the plaintext's maximum length, and MaxImage is the +/// ciphertext's maximum length. +/// \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), +/// RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE TrapdoorFunctionBounds { public: virtual ~TrapdoorFunctionBounds() {} - //! \brief Returns the maximum size of a message before the trapdoor function is applied - //! \returns the maximum size of a message before the trapdoor function is applied - //! \details Derived classes must implement PreimageBound(). + /// \brief Returns the maximum size of a message before the trapdoor function is applied + /// \returns the maximum size of a message before the trapdoor function is applied + /// \details Derived classes must implement PreimageBound(). virtual Integer PreimageBound() const =0; - //! \brief Returns the maximum size of a message after the trapdoor function is applied - //! \returns the maximum size of a message after the trapdoor function is applied - //! \details Derived classes must implement ImageBound(). + /// \brief Returns the maximum size of a message after the trapdoor function is applied + /// \returns the maximum size of a message after the trapdoor function is applied + /// \details Derived classes must implement ImageBound(). virtual Integer ImageBound() const =0; - //! \brief Returns the maximum size of a message before the trapdoor function is applied bound to a public key - //! \returns the maximum size of a message before the trapdoor function is applied bound to a public key - //! \details The default implementation returns PreimageBound() - 1. + /// \brief Returns the maximum size of a message before the trapdoor function is applied bound to a public key + /// \returns the maximum size of a message before the trapdoor function is applied bound to a public key + /// \details The default implementation returns PreimageBound() - 1. virtual Integer MaxPreimage() const {return --PreimageBound();} - //! \brief Returns the maximum size of a message after the trapdoor function is applied bound to a public key - //! \returns the the maximum size of a message after the trapdoor function is applied bound to a public key - //! \details The default implementation returns ImageBound() - 1. + /// \brief Returns the maximum size of a message after the trapdoor function is applied bound to a public key + /// \returns the the maximum size of a message after the trapdoor function is applied bound to a public key + /// \details The default implementation returns ImageBound() - 1. virtual Integer MaxImage() const {return --ImageBound();} }; -//! \class RandomizedTrapdoorFunction -//! \brief Applies the trapdoor function, using random data if required -//! \details ApplyFunction() is the foundation for encrypting a message under a public key. -//! Derived classes will override it at some point. -//! \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), -//! RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() +/// \class RandomizedTrapdoorFunction +/// \brief Applies the trapdoor function, using random data if required +/// \details ApplyFunction() is the foundation for encrypting a message under a public key. +/// Derived classes will override it at some point. +/// \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), +/// RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE RandomizedTrapdoorFunction : public TrapdoorFunctionBounds { public: virtual ~RandomizedTrapdoorFunction() {} - //! \brief Applies the trapdoor function, using random data if required - //! \param rng a RandomNumberGenerator derived class - //! \param x the message on which the encryption function is applied - //! \returns the message x encrypted under the public key - //! \details ApplyRandomizedFunction is a generalization of encryption under a public key - //! cryptosystem. The RandomNumberGenerator may (or may not) be required. - //! Derived classes must implement it. + /// \brief Applies the trapdoor function, using random data if required + /// \param rng a RandomNumberGenerator derived class + /// \param x the message on which the encryption function is applied + /// \returns the message x encrypted under the public key + /// \details ApplyRandomizedFunction is a generalization of encryption under a public key + /// cryptosystem. The RandomNumberGenerator may (or may not) be required. + /// Derived classes must implement it. virtual Integer ApplyRandomizedFunction(RandomNumberGenerator &rng, const Integer &x) const =0; - //! \brief Determines if the encryption algorithm is randomized - //! \returns true if the encryption algorithm is randomized, false otherwise - //! \details If IsRandomized() returns false, then NullRNG() can be used. + /// \brief Determines if the encryption algorithm is randomized + /// \returns true if the encryption algorithm is randomized, false otherwise + /// \details If IsRandomized() returns false, then NullRNG() can be used. virtual bool IsRandomized() const {return true;} }; -//! \class TrapdoorFunction -//! \brief Applies the trapdoor function -//! \details ApplyFunction() is the foundation for encrypting a message under a public key. -//! Derived classes will override it at some point. -//! \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), -//! RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() +/// \class TrapdoorFunction +/// \brief Applies the trapdoor function +/// \details ApplyFunction() is the foundation for encrypting a message under a public key. +/// Derived classes will override it at some point. +/// \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), +/// RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE TrapdoorFunction : public RandomizedTrapdoorFunction { public: virtual ~TrapdoorFunction() {} - //! \brief Applies the trapdoor function - //! \param rng a RandomNumberGenerator derived class - //! \param x the message on which the encryption function is applied - //! \details ApplyRandomizedFunction is a generalization of encryption under a public key - //! cryptosystem. The RandomNumberGenerator may (or may not) be required. - //! \details Internally, ApplyRandomizedFunction() calls ApplyFunction() \a - //! without the RandomNumberGenerator. + /// \brief Applies the trapdoor function + /// \param rng a RandomNumberGenerator derived class + /// \param x the message on which the encryption function is applied + /// \details ApplyRandomizedFunction is a generalization of encryption under a public key + /// cryptosystem. The RandomNumberGenerator may (or may not) be required. + /// \details Internally, ApplyRandomizedFunction() calls ApplyFunction() \a + /// without the RandomNumberGenerator. Integer ApplyRandomizedFunction(RandomNumberGenerator &rng, const Integer &x) const {CRYPTOPP_UNUSED(rng); return ApplyFunction(x);} bool IsRandomized() const {return false;} - //! \brief Applies the trapdoor - //! \param x the message on which the encryption function is applied - //! \returns the message x encrypted under the public key - //! \details ApplyFunction is a generalization of encryption under a public key - //! cryptosystem. Derived classes must implement it. + /// \brief Applies the trapdoor + /// \param x the message on which the encryption function is applied + /// \returns the message x encrypted under the public key + /// \details ApplyFunction is a generalization of encryption under a public key + /// cryptosystem. Derived classes must implement it. virtual Integer ApplyFunction(const Integer &x) const =0; }; -//! \class RandomizedTrapdoorFunctionInverse -//! \brief Applies the inverse of the trapdoor function, using random data if required -//! \details CalculateInverse() is the foundation for decrypting a message under a private key -//! in a public key cryptosystem. Derived classes will override it at some point. -//! \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), -//! RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() +/// \class RandomizedTrapdoorFunctionInverse +/// \brief Applies the inverse of the trapdoor function, using random data if required +/// \details CalculateInverse() is the foundation for decrypting a message under a private key +/// in a public key cryptosystem. Derived classes will override it at some point. +/// \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), +/// RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE RandomizedTrapdoorFunctionInverse { public: virtual ~RandomizedTrapdoorFunctionInverse() {} - //! \brief Applies the inverse of the trapdoor function, using random data if required - //! \param rng a RandomNumberGenerator derived class - //! \param x the message on which the decryption function is applied - //! \returns the message x decrypted under the private key - //! \details CalculateRandomizedInverse is a generalization of decryption using the private key - //! The RandomNumberGenerator may (or may not) be required. Derived classes must implement it. + /// \brief Applies the inverse of the trapdoor function, using random data if required + /// \param rng a RandomNumberGenerator derived class + /// \param x the message on which the decryption function is applied + /// \returns the message x decrypted under the private key + /// \details CalculateRandomizedInverse is a generalization of decryption using the private key + /// The RandomNumberGenerator may (or may not) be required. Derived classes must implement it. virtual Integer CalculateRandomizedInverse(RandomNumberGenerator &rng, const Integer &x) const =0; - //! \brief Determines if the decryption algorithm is randomized - //! \returns true if the decryption algorithm is randomized, false otherwise - //! \details If IsRandomized() returns false, then NullRNG() can be used. + /// \brief Determines if the decryption algorithm is randomized + /// \returns true if the decryption algorithm is randomized, false otherwise + /// \details If IsRandomized() returns false, then NullRNG() can be used. virtual bool IsRandomized() const {return true;} }; -//! \class TrapdoorFunctionInverse -//! \brief Applies the inverse of the trapdoor function -//! \details CalculateInverse() is the foundation for decrypting a message under a private key -//! in a public key cryptosystem. Derived classes will override it at some point. -//! \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), -//! RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() +/// \class TrapdoorFunctionInverse +/// \brief Applies the inverse of the trapdoor function +/// \details CalculateInverse() is the foundation for decrypting a message under a private key +/// in a public key cryptosystem. Derived classes will override it at some point. +/// \sa TrapdoorFunctionBounds(), RandomizedTrapdoorFunction(), TrapdoorFunction(), +/// RandomizedTrapdoorFunctionInverse() and TrapdoorFunctionInverse() class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE TrapdoorFunctionInverse : public RandomizedTrapdoorFunctionInverse { public: virtual ~TrapdoorFunctionInverse() {} - //! \brief Applies the inverse of the trapdoor function - //! \param rng a RandomNumberGenerator derived class - //! \param x the message on which the decryption function is applied - //! \returns the message x decrypted under the private key - //! \details CalculateRandomizedInverse is a generalization of decryption using the private key - //! \details Internally, CalculateRandomizedInverse() calls CalculateInverse() \a - //! without the RandomNumberGenerator. + /// \brief Applies the inverse of the trapdoor function + /// \param rng a RandomNumberGenerator derived class + /// \param x the message on which the decryption function is applied + /// \returns the message x decrypted under the private key + /// \details CalculateRandomizedInverse is a generalization of decryption using the private key + /// \details Internally, CalculateRandomizedInverse() calls CalculateInverse() \a + /// without the RandomNumberGenerator. Integer CalculateRandomizedInverse(RandomNumberGenerator &rng, const Integer &x) const {return CalculateInverse(rng, x);} - //! \brief Determines if the decryption algorithm is randomized - //! \returns true if the decryption algorithm is randomized, false otherwise - //! \details If IsRandomized() returns false, then NullRNG() can be used. + /// \brief Determines if the decryption algorithm is randomized + /// \returns true if the decryption algorithm is randomized, false otherwise + /// \details If IsRandomized() returns false, then NullRNG() can be used. bool IsRandomized() const {return false;} - //! \brief Calculates the inverse of an element - //! \param rng a RandomNumberGenerator derived class - //! \param x the element - //! \returns the inverse of the element in the group + /// \brief Calculates the inverse of an element + /// \param rng a RandomNumberGenerator derived class + /// \param x the element + /// \returns the inverse of the element in the group virtual Integer CalculateInverse(RandomNumberGenerator &rng, const Integer &x) const =0; }; // ******************************************************** -//! \class PK_EncryptionMessageEncodingMethod -//! \brief Message encoding method for public key encryption +/// \class PK_EncryptionMessageEncodingMethod +/// \brief Message encoding method for public key encryption class CRYPTOPP_NO_VTABLE PK_EncryptionMessageEncodingMethod { public: @@ -219,7 +219,7 @@ public: virtual bool ParameterSupported(const char *name) const {CRYPTOPP_UNUSED(name); return false;} - //! max size of unpadded message in bytes, given max size of padded message in bits (1 less than size of modulus) + /// max size of unpadded message in bytes, given max size of padded message in bits (1 less than size of modulus) virtual size_t MaxUnpaddedLength(size_t paddedLength) const =0; virtual void Pad(RandomNumberGenerator &rng, const byte *raw, size_t inputLength, byte *padded, size_t paddedBitLength, const NameValuePairs ¶meters) const =0; @@ -229,10 +229,10 @@ public: // ******************************************************** -//! \class TF_Base -//! \brief The base for trapdoor based cryptosystems -//! \tparam TFI trapdoor function interface derived class -//! \tparam MEI message encoding interface derived class +/// \class TF_Base +/// \brief The base for trapdoor based cryptosystems +/// \tparam TFI trapdoor function interface derived class +/// \tparam MEI message encoding interface derived class template class CRYPTOPP_NO_VTABLE TF_Base { @@ -250,9 +250,9 @@ protected: // ******************************************************** -//! \class PK_FixedLengthCryptoSystemImpl -//! \brief Public key trapdoor function default implementation -//! \tparam BASE public key cryptosystem with a fixed length +/// \class PK_FixedLengthCryptoSystemImpl +/// \brief Public key trapdoor function default implementation +/// \tparam BASE public key cryptosystem with a fixed length template class CRYPTOPP_NO_VTABLE PK_FixedLengthCryptoSystemImpl : public BASE { @@ -268,10 +268,10 @@ public: virtual size_t FixedCiphertextLength() const =0; }; -//! \class TF_CryptoSystemBase -//! \brief Trapdoor function cryptosystem base class -//! \tparam INTFACE public key cryptosystem base interface -//! \tparam BASE public key cryptosystem implementation base +/// \class TF_CryptoSystemBase +/// \brief Trapdoor function cryptosystem base class +/// \tparam INTFACE public key cryptosystem base interface +/// \tparam BASE public key cryptosystem implementation base template class CRYPTOPP_NO_VTABLE TF_CryptoSystemBase : public PK_FixedLengthCryptoSystemImpl, protected BASE { @@ -288,8 +288,8 @@ protected: size_t PaddedBlockBitLength() const {return SaturatingSubtract(this->GetTrapdoorFunctionBounds().PreimageBound().BitCount(),1U);} }; -//! \class TF_DecryptorBase -//! \brief Trapdoor function cryptosystems decryption base class +/// \class TF_DecryptorBase +/// \brief Trapdoor function cryptosystems decryption base class class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE TF_DecryptorBase : public TF_CryptoSystemBase > { public: @@ -298,8 +298,8 @@ public: DecodingResult Decrypt(RandomNumberGenerator &rng, const byte *ciphertext, size_t ciphertextLength, byte *plaintext, const NameValuePairs ¶meters = g_nullNameValuePairs) const; }; -//! \class TF_EncryptorBase -//! \brief Trapdoor function cryptosystems encryption base class +/// \class TF_EncryptorBase +/// \brief Trapdoor function cryptosystems encryption base class class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE TF_EncryptorBase : public TF_CryptoSystemBase > { public: @@ -313,12 +313,12 @@ public: // Typedef change due to Clang, http://github.com/weidai11/cryptopp/issues/300 typedef std::pair HashIdentifier; -//! \class PK_SignatureMessageEncodingMethod -//! \brief Interface for message encoding method for public key signature schemes. -//! \details PK_SignatureMessageEncodingMethod provides interfaces for message -//! encoding method for public key signature schemes. The methods support both -//! trapdoor functions (TF_*) and discrete logarithm (DL_*) -//! based schemes. +/// \class PK_SignatureMessageEncodingMethod +/// \brief Interface for message encoding method for public key signature schemes. +/// \details PK_SignatureMessageEncodingMethod provides interfaces for message +/// encoding method for public key signature schemes. The methods support both +/// trapdoor functions (TF_*) and discrete logarithm (DL_*) +/// based schemes. class CRYPTOPP_NO_VTABLE PK_SignatureMessageEncodingMethod { public: @@ -329,12 +329,12 @@ public: virtual size_t MaxRecoverableLength(size_t representativeBitLength, size_t hashIdentifierLength, size_t digestLength) const {CRYPTOPP_UNUSED(representativeBitLength); CRYPTOPP_UNUSED(representativeBitLength); CRYPTOPP_UNUSED(hashIdentifierLength); CRYPTOPP_UNUSED(digestLength); return 0;} - //! \brief Determines whether an encoding method requires a random number generator - //! \return true if the encoding method requires a RandomNumberGenerator() - //! \details if IsProbabilistic() returns false, then NullRNG() can be passed to functions that take - //! RandomNumberGenerator(). - //! \sa Bellare and RogawayPSS: - //! Provably Secure Encoding Method for Digital Signatures + /// \brief Determines whether an encoding method requires a random number generator + /// \return true if the encoding method requires a RandomNumberGenerator() + /// \details if IsProbabilistic() returns false, then NullRNG() can be passed to functions that take + /// RandomNumberGenerator(). + /// \sa Bellare and RogawayPSS: + /// Provably Secure Encoding Method for Digital Signatures bool IsProbabilistic() const {return true;} bool AllowNonrecoverablePart() const @@ -397,10 +397,10 @@ public: }; }; -//! \class PK_DeterministicSignatureMessageEncodingMethod -//! \brief Interface for message encoding method for public key signature schemes. -//! \details PK_DeterministicSignatureMessageEncodingMethod provides interfaces -//! for message encoding method for public key signature schemes. +/// \class PK_DeterministicSignatureMessageEncodingMethod +/// \brief Interface for message encoding method for public key signature schemes. +/// \details PK_DeterministicSignatureMessageEncodingMethod provides interfaces +/// for message encoding method for public key signature schemes. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_DeterministicSignatureMessageEncodingMethod : public PK_SignatureMessageEncodingMethod { public: @@ -409,10 +409,10 @@ public: byte *representative, size_t representativeBitLength) const; }; -//! \class PK_RecoverableSignatureMessageEncodingMethod -//! \brief Interface for message encoding method for public key signature schemes. -//! \details PK_RecoverableSignatureMessageEncodingMethod provides interfaces -//! for message encoding method for public key signature schemes. +/// \class PK_RecoverableSignatureMessageEncodingMethod +/// \brief Interface for message encoding method for public key signature schemes. +/// \details PK_RecoverableSignatureMessageEncodingMethod provides interfaces +/// for message encoding method for public key signature schemes. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_RecoverableSignatureMessageEncodingMethod : public PK_SignatureMessageEncodingMethod { public: @@ -421,10 +421,10 @@ public: byte *representative, size_t representativeBitLength) const; }; -//! \class DL_SignatureMessageEncodingMethod_DSA -//! \brief Interface for message encoding method for public key signature schemes. -//! \details DL_SignatureMessageEncodingMethod_DSA provides interfaces -//! for message encoding method for DSA. +/// \class DL_SignatureMessageEncodingMethod_DSA +/// \brief Interface for message encoding method for public key signature schemes. +/// \details DL_SignatureMessageEncodingMethod_DSA provides interfaces +/// for message encoding method for DSA. class CRYPTOPP_DLL DL_SignatureMessageEncodingMethod_DSA : public PK_DeterministicSignatureMessageEncodingMethod { public: @@ -434,10 +434,10 @@ public: byte *representative, size_t representativeBitLength) const; }; -//! \class DL_SignatureMessageEncodingMethod_NR -//! \brief Interface for message encoding method for public key signature schemes. -//! \details DL_SignatureMessageEncodingMethod_NR provides interfaces -//! for message encoding method for Nyberg-Rueppel. +/// \class DL_SignatureMessageEncodingMethod_NR +/// \brief Interface for message encoding method for public key signature schemes. +/// \details DL_SignatureMessageEncodingMethod_NR provides interfaces +/// for message encoding method for Nyberg-Rueppel. class CRYPTOPP_DLL DL_SignatureMessageEncodingMethod_NR : public PK_DeterministicSignatureMessageEncodingMethod { public: @@ -447,10 +447,10 @@ public: byte *representative, size_t representativeBitLength) const; }; -//! \class DL_SignatureMessageEncodingMethod_SM2 -//! \brief Interface for message encoding method for public key signature schemes. -//! \details DL_SignatureMessageEncodingMethod_SM2 provides interfaces -//! for message encoding method for SM2. +/// \class DL_SignatureMessageEncodingMethod_SM2 +/// \brief Interface for message encoding method for public key signature schemes. +/// \details DL_SignatureMessageEncodingMethod_SM2 provides interfaces +/// for message encoding method for SM2. class CRYPTOPP_DLL DL_SignatureMessageEncodingMethod_SM2 : public PK_DeterministicSignatureMessageEncodingMethod { public: @@ -460,10 +460,10 @@ public: byte *representative, size_t representativeBitLength) const; }; -//! \class PK_MessageAccumulatorBase -//! \brief Interface for message encoding method for public key signature schemes. -//! \details PK_MessageAccumulatorBase provides interfaces -//! for message encoding method. +/// \class PK_MessageAccumulatorBase +/// \brief Interface for message encoding method for public key signature schemes. +/// \details PK_MessageAccumulatorBase provides interfaces +/// for message encoding method. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_MessageAccumulatorBase : public PK_MessageAccumulator { public: @@ -482,10 +482,10 @@ public: bool m_empty; }; -//! \class PK_MessageAccumulatorImpl -//! \brief Interface for message encoding method for public key signature schemes. -//! \details PK_MessageAccumulatorBase provides interfaces -//! for message encoding method. +/// \class PK_MessageAccumulatorImpl +/// \brief Interface for message encoding method for public key signature schemes. +/// \details PK_MessageAccumulatorBase provides interfaces +/// for message encoding method. template class PK_MessageAccumulatorImpl : public PK_MessageAccumulatorBase, protected ObjectHolder { @@ -493,10 +493,10 @@ public: HashTransformation & AccessHash() {return this->m_object;} }; -//! \class TF_SignatureSchemeBase -//! \brief Trapdoor Function (TF) Signature Scheme base class -//! \tparam INTFACE interface -//! \tparam BASE base class +/// \class TF_SignatureSchemeBase +/// \brief Trapdoor Function (TF) Signature Scheme base class +/// \tparam INTFACE interface +/// \tparam BASE base class template class CRYPTOPP_NO_VTABLE TF_SignatureSchemeBase : public INTFACE, protected BASE { @@ -525,8 +525,8 @@ protected: virtual size_t GetDigestSize() const =0; }; -//! \class TF_SignerBase -//! \brief Trapdoor Function (TF) Signer base class +/// \class TF_SignerBase +/// \brief Trapdoor Function (TF) Signer base class class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE TF_SignerBase : public TF_SignatureSchemeBase > { public: @@ -536,8 +536,8 @@ public: size_t SignAndRestart(RandomNumberGenerator &rng, PK_MessageAccumulator &messageAccumulator, byte *signature, bool restart=true) const; }; -//! \class TF_VerifierBase -//! \brief Trapdoor Function (TF) Verifier base class +/// \class TF_VerifierBase +/// \brief Trapdoor Function (TF) Verifier base class class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE TF_VerifierBase : public TF_SignatureSchemeBase > { public: @@ -550,11 +550,11 @@ public: // ******************************************************** -//! \class TF_CryptoSchemeOptions -//! \brief Trapdoor Function (TF) scheme options -//! \tparam T1 algorithm info class -//! \tparam T2 keys class with public and private key -//! \tparam T3 message encoding class +/// \class TF_CryptoSchemeOptions +/// \brief Trapdoor Function (TF) scheme options +/// \tparam T1 algorithm info class +/// \tparam T2 keys class with public and private key +/// \tparam T3 message encoding class template struct TF_CryptoSchemeOptions { @@ -565,23 +565,23 @@ struct TF_CryptoSchemeOptions typedef T3 MessageEncodingMethod; }; -//! \class TF_SignatureSchemeOptions -//! \brief Trapdoor Function (TF) signature scheme options -//! \tparam T1 algorithm info class -//! \tparam T2 keys class with public and private key -//! \tparam T3 message encoding class -//! \tparam T4 HashTransformation class +/// \class TF_SignatureSchemeOptions +/// \brief Trapdoor Function (TF) signature scheme options +/// \tparam T1 algorithm info class +/// \tparam T2 keys class with public and private key +/// \tparam T3 message encoding class +/// \tparam T4 HashTransformation class template struct TF_SignatureSchemeOptions : public TF_CryptoSchemeOptions { typedef T4 HashFunction; }; -//! \class TF_ObjectImplBase -//! \brief Trapdoor Function (TF) base implementation -//! \tparam BASE base class -//! \tparam SCHEME_OPTIONS scheme options class -//! \tparam KEY_CLASS key class +/// \class TF_ObjectImplBase +/// \brief Trapdoor Function (TF) base implementation +/// \tparam BASE base class +/// \tparam SCHEME_OPTIONS scheme options class +/// \tparam KEY_CLASS key class template class CRYPTOPP_NO_VTABLE TF_ObjectImplBase : public AlgorithmImpl { @@ -633,12 +633,12 @@ protected: } }; -//! \class TF_ObjectImplExtRef -//! \brief Trapdoor Function (TF) signature with external reference -//! \tparam BASE base class -//! \tparam SCHEME_OPTIONS scheme options class -//! \tparam KEY key class -//! \details TF_ObjectImplExtRef() holds a pointer to an external key structure +/// \class TF_ObjectImplExtRef +/// \brief Trapdoor Function (TF) signature with external reference +/// \tparam BASE base class +/// \tparam SCHEME_OPTIONS scheme options class +/// \tparam KEY key class +/// \details TF_ObjectImplExtRef() holds a pointer to an external key structure template class TF_ObjectImplExtRef : public TF_ObjectImplBase { @@ -655,12 +655,12 @@ private: const KEY * m_pKey; }; -//! \class TF_ObjectImpl -//! \brief Trapdoor Function (TF) signature scheme options -//! \tparam BASE base class -//! \tparam SCHEME_OPTIONS scheme options class -//! \tparam KEY_CLASS key class -//! \details TF_ObjectImpl() holds a reference to a trapdoor function +/// \class TF_ObjectImpl +/// \brief Trapdoor Function (TF) signature scheme options +/// \tparam BASE base class +/// \tparam SCHEME_OPTIONS scheme options class +/// \tparam KEY_CLASS key class +/// \details TF_ObjectImpl() holds a reference to a trapdoor function template class CRYPTOPP_NO_VTABLE TF_ObjectImpl : public TF_ObjectImplBase { @@ -676,33 +676,33 @@ private: KeyClass m_trapdoorFunction; }; -//! \class TF_DecryptorImpl -//! \brief Trapdoor Function (TF) decryptor options -//! \tparam SCHEME_OPTIONS scheme options class +/// \class TF_DecryptorImpl +/// \brief Trapdoor Function (TF) decryptor options +/// \tparam SCHEME_OPTIONS scheme options class template class TF_DecryptorImpl : public TF_ObjectImpl { }; -//! \class TF_EncryptorImpl -//! \brief Trapdoor Function (TF) encryptor options -//! \tparam SCHEME_OPTIONS scheme options class +/// \class TF_EncryptorImpl +/// \brief Trapdoor Function (TF) encryptor options +/// \tparam SCHEME_OPTIONS scheme options class template class TF_EncryptorImpl : public TF_ObjectImpl { }; -//! \class TF_SignerImpl -//! \brief Trapdoor Function (TF) encryptor options -//! \tparam SCHEME_OPTIONS scheme options class +/// \class TF_SignerImpl +/// \brief Trapdoor Function (TF) encryptor options +/// \tparam SCHEME_OPTIONS scheme options class template class TF_SignerImpl : public TF_ObjectImpl { }; -//! \class TF_VerifierImpl -//! \brief Trapdoor Function (TF) encryptor options -//! \tparam SCHEME_OPTIONS scheme options class +/// \class TF_VerifierImpl +/// \brief Trapdoor Function (TF) encryptor options +/// \tparam SCHEME_OPTIONS scheme options class template class TF_VerifierImpl : public TF_ObjectImpl { @@ -710,38 +710,38 @@ class TF_VerifierImpl : public TF_ObjectImpl class P1363_KDF2 { @@ -770,17 +770,17 @@ public: // ******************************************************** -//! \brief Exception thrown when an invalid group element is encountered -//! \details Thrown by DecodeElement and AgreeWithStaticPrivateKey +/// \brief Exception thrown when an invalid group element is encountered +/// \details Thrown by DecodeElement and AgreeWithStaticPrivateKey class DL_BadElement : public InvalidDataFormat { public: DL_BadElement() : InvalidDataFormat("CryptoPP: invalid group element") {} }; -//! \brief Interface for Discrete Log (DL) group parameters -//! \tparam T element in the group -//! \details The element is usually an Integer, \ref ECP "ECP::Point" or \ref EC2N "EC2N::Point" +/// \brief Interface for Discrete Log (DL) group parameters +/// \tparam T element in the group +/// \details The element is usually an Integer, \ref ECP "ECP::Point" or \ref EC2N "EC2N::Point" template class CRYPTOPP_NO_VTABLE DL_GroupParameters : public CryptoParameters { @@ -836,29 +836,29 @@ public: GetBasePrecomputation().Save(GetGroupPrecomputation(), storedPrecomputation); } - //! \brief Retrieves the subgroup generator - //! \return the subgroup generator - //! \details The subgroup generator is retrieved from the base precomputation + /// \brief Retrieves the subgroup generator + /// \return the subgroup generator + /// \details The subgroup generator is retrieved from the base precomputation virtual const Element & GetSubgroupGenerator() const {return GetBasePrecomputation().GetBase(GetGroupPrecomputation());} - //! \brief Sets the subgroup generator - //! \param base the new subgroup generator - //! \details The subgroup generator is set in the base precomputation + /// \brief Sets the subgroup generator + /// \param base the new subgroup generator + /// \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 Retrieves the subgroup generator + /// \return the subgroup generator + /// \details The subgroup generator is retrieved from the base precomputation. virtual Element ExponentiateBase(const Integer &exponent) const { return GetBasePrecomputation().Exponentiate(GetGroupPrecomputation(), exponent); } - //! \brief Exponentiates an element - //! \param base the base elemenet - //! \param exponent the exponent to raise the base - //! \return the result of the exponentiation - //! \details Internally, ExponentiateElement() calls SimultaneousExponentiate(). + /// \brief Exponentiates an element + /// \param base the base elemenet + /// \param exponent the exponent to raise the base + /// \return the result of the exponentiation + /// \details Internally, ExponentiateElement() calls SimultaneousExponentiate(). virtual Element ExponentiateElement(const Element &base, const Integer &exponent) const { Element result; @@ -866,119 +866,119 @@ public: return result; } - //! \brief Retrieves the group precomputation - //! \return a const reference to the group precomputation + /// \brief Retrieves the group precomputation + /// \return a const reference to the group precomputation virtual const DL_GroupPrecomputation & GetGroupPrecomputation() const =0; - //! \brief Retrieves the group precomputation - //! \return a const reference to the group precomputation using a fixed base + /// \brief Retrieves the group precomputation + /// \return a const reference to the group precomputation using a fixed base virtual const DL_FixedBasePrecomputation & GetBasePrecomputation() const =0; - //! \brief Retrieves the group precomputation - //! \return a non-const reference to the group precomputation using a fixed base + /// \brief Retrieves the group precomputation + /// \return a non-const reference to the group precomputation using a fixed base virtual DL_FixedBasePrecomputation & AccessBasePrecomputation() =0; - //! \brief Retrieves the subgroup order - //! \return the order of subgroup generated by the base element + /// \brief Retrieves the subgroup order + /// \return the order of subgroup generated by the base element virtual const Integer & GetSubgroupOrder() const =0; - //! \brief Retrieves the maximum exponent for the group - //! \return the maximum exponent for the group + /// \brief Retrieves the maximum exponent for the group + /// \return the maximum exponent for the group virtual Integer GetMaxExponent() const =0; - //! \brief Retrieves the order of the group - //! \return the order of the group - //! \details Either GetGroupOrder() or GetCofactor() must be overridden in a derived class. + /// \brief Retrieves the order of the group + /// \return the order of the group + /// \details Either GetGroupOrder() or GetCofactor() must be overridden in a derived class. virtual Integer GetGroupOrder() const {return GetSubgroupOrder()*GetCofactor();} - //! \brief Retrieves the cofactor - //! \return the cofactor - //! \details Either GetGroupOrder() or GetCofactor() must be overridden in a derived class. + /// \brief Retrieves the cofactor + /// \return the cofactor + /// \details Either GetGroupOrder() or GetCofactor() must be overridden in a derived class. virtual Integer GetCofactor() const {return GetGroupOrder()/GetSubgroupOrder();} - //! \brief Retrieves the encoded element's size - //! \param reversible flag indicating the encoding format - //! \return encoded element's size, in bytes - //! \details The format of the encoded element varies by the underlyinhg type of the element and the - //! reversible flag. GetEncodedElementSize() must be implemented in a derived class. - //! \sa GetEncodedElementSize(), EncodeElement(), DecodeElement() + /// \brief Retrieves the encoded element's size + /// \param reversible flag indicating the encoding format + /// \return encoded element's size, in bytes + /// \details The format of the encoded element varies by the underlyinhg type of the element and the + /// reversible flag. GetEncodedElementSize() must be implemented in a derived class. + /// \sa GetEncodedElementSize(), EncodeElement(), DecodeElement() virtual unsigned int GetEncodedElementSize(bool reversible) const =0; - //! \brief Encodes the element - //! \param reversible flag indicating the encoding format - //! \param element reference to the element to encode - //! \param encoded destination byte array for the encoded element - //! \details EncodeElement() must be implemented in a derived class. - //! \pre COUNTOF(encoded) == GetEncodedElementSize() + /// \brief Encodes the element + /// \param reversible flag indicating the encoding format + /// \param element reference to the element to encode + /// \param encoded destination byte array for the encoded element + /// \details EncodeElement() must be implemented in a derived class. + /// \pre COUNTOF(encoded) == GetEncodedElementSize() virtual void EncodeElement(bool reversible, const Element &element, byte *encoded) const =0; - //! \brief Decodes the element - //! \param encoded byte array with the encoded element - //! \param checkForGroupMembership flag indicating if the element should be validated - //! \return Element after decoding - //! \details DecodeElement() must be implemented in a derived class. - //! \pre COUNTOF(encoded) == GetEncodedElementSize() + /// \brief Decodes the element + /// \param encoded byte array with the encoded element + /// \param checkForGroupMembership flag indicating if the element should be validated + /// \return Element after decoding + /// \details DecodeElement() must be implemented in a derived class. + /// \pre COUNTOF(encoded) == GetEncodedElementSize() virtual Element DecodeElement(const byte *encoded, bool checkForGroupMembership) const =0; - //! \brief Converts an element to an Integer - //! \param element the element to convert to an Integer - //! \return Element after converting to an Integer - //! \details ConvertElementToInteger() must be implemented in a derived class. + /// \brief Converts an element to an Integer + /// \param element the element to convert to an Integer + /// \return Element after converting to an Integer + /// \details ConvertElementToInteger() must be implemented in a derived class. virtual Integer ConvertElementToInteger(const Element &element) const =0; - //! \brief Check the group for errors - //! \param rng RandomNumberGenerator for objects which use randomized testing - //! \param level level of thoroughness - //! \return true if the tests succeed, false otherwise - //! \details There are four levels of thoroughness: - //!
    - //!
  • 0 - using this object won't cause a crash or exception - //!
  • 1 - this object will probably function, and encrypt, sign, other operations correctly - //!
  • 2 - ensure this object will function correctly, and perform reasonable security checks - //!
  • 3 - perform reasonable security checks, and do checks that may take a long time - //!
- //! \details Level 0 does not require a RandomNumberGenerator. A NullRNG() can be used for level 0. - //! Level 1 may not check for weak keys and such. Levels 2 and 3 are recommended. - //! \details ValidateGroup() must be implemented in a derived class. + /// \brief Check the group for errors + /// \param rng RandomNumberGenerator for objects which use randomized testing + /// \param level level of thoroughness + /// \return true if the tests succeed, false otherwise + /// \details There are four levels of thoroughness: + ///
    + ///
  • 0 - using this object won't cause a crash or exception + ///
  • 1 - this object will probably function, and encrypt, sign, other operations correctly + ///
  • 2 - ensure this object will function correctly, and perform reasonable security checks + ///
  • 3 - perform reasonable security checks, and do checks that may take a long time + ///
+ /// \details Level 0 does not require a RandomNumberGenerator. A NullRNG() can be used for level 0. + /// Level 1 may not check for weak keys and such. Levels 2 and 3 are recommended. + /// \details ValidateGroup() must be implemented in a derived class. virtual bool ValidateGroup(RandomNumberGenerator &rng, unsigned int level) const =0; - //! \brief Check the element for errors - //! \param level level of thoroughness - //! \param element element to check - //! \param precomp optional pointer to DL_FixedBasePrecomputation - //! \return true if the tests succeed, false otherwise - //! \details There are four levels of thoroughness: - //!
    - //!
  • 0 - using this object won't cause a crash or exception - //!
  • 1 - this object will probably function, and encrypt, sign, other operations correctly - //!
  • 2 - ensure this object will function correctly, and perform reasonable security checks - //!
  • 3 - perform reasonable security checks, and do checks that may take a long time - //!
- //! \details Level 0 performs group membership checks. Level 1 may not check for weak keys and such. - //! Levels 2 and 3 are recommended. - //! \details ValidateElement() must be implemented in a derived class. + /// \brief Check the element for errors + /// \param level level of thoroughness + /// \param element element to check + /// \param precomp optional pointer to DL_FixedBasePrecomputation + /// \return true if the tests succeed, false otherwise + /// \details There are four levels of thoroughness: + ///
    + ///
  • 0 - using this object won't cause a crash or exception + ///
  • 1 - this object will probably function, and encrypt, sign, other operations correctly + ///
  • 2 - ensure this object will function correctly, and perform reasonable security checks + ///
  • 3 - perform reasonable security checks, and do checks that may take a long time + ///
+ /// \details Level 0 performs group membership checks. Level 1 may not check for weak keys and such. + /// Levels 2 and 3 are recommended. + /// \details ValidateElement() must be implemented in a derived class. virtual bool ValidateElement(unsigned int level, const Element &element, const DL_FixedBasePrecomputation *precomp) const =0; virtual bool FastSubgroupCheckAvailable() const =0; - //! \brief Determines if an element is an identity - //! \param element element to check - //! \return true if the element is an identity, false otherwise - //! \details The identity element or or neutral element is a special element in a group that leaves - //! other elements unchanged when combined with it. - //! \details IsIdentity() must be implemented in a derived class. + /// \brief Determines if an element is an identity + /// \param element element to check + /// \return true if the element is an identity, false otherwise + /// \details The identity element or or neutral element is a special element in a group that leaves + /// other elements unchanged when combined with it. + /// \details IsIdentity() must be implemented in a derived class. virtual bool IsIdentity(const Element &element) const =0; - //! \brief Exponentiates a base to multiple exponents - //! \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 + /// \brief Exponentiates a base to multiple exponents + /// \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 virtual void SimultaneousExponentiate(Element *results, const Element &base, const Integer *exponents, unsigned int exponentsCount) const =0; protected: @@ -988,10 +988,10 @@ private: mutable unsigned int m_validationLevel; }; -//! \brief Base implementation of Discrete Log (DL) group parameters -//! \tparam GROUP_PRECOMP group precomputation class -//! \tparam BASE_PRECOMP fixed base precomputation class -//! \tparam BASE class or type of an element +/// \brief Base implementation of Discrete Log (DL) group parameters +/// \tparam GROUP_PRECOMP group precomputation class +/// \tparam BASE_PRECOMP fixed base precomputation class +/// \tparam BASE class or type of an element template , class BASE = DL_GroupParameters > class DL_GroupParametersImpl : public BASE { @@ -1002,16 +1002,16 @@ public: virtual ~DL_GroupParametersImpl() {} - //! \brief Retrieves the group precomputation - //! \return a const reference to the group precomputation + /// \brief Retrieves the group precomputation + /// \return a const reference to the group precomputation const DL_GroupPrecomputation & GetGroupPrecomputation() const {return m_groupPrecomputation;} - //! \brief Retrieves the group precomputation - //! \return a const reference to the group precomputation using a fixed base + /// \brief Retrieves the group precomputation + /// \return a const reference to the group precomputation using a fixed base const DL_FixedBasePrecomputation & GetBasePrecomputation() const {return m_gpc;} - //! \brief Retrieves the group precomputation - //! \return a non-const reference to the group precomputation using a fixed base + /// \brief Retrieves the group precomputation + /// \return a non-const reference to the group precomputation using a fixed base DL_FixedBasePrecomputation & AccessBasePrecomputation() {return m_gpc;} protected: @@ -1019,24 +1019,24 @@ protected: BASE_PRECOMP m_gpc; }; -//! \brief Base class for a Discrete Log (DL) key -//! \tparam T class or type of an element -//! \details The element is usually an Integer, \ref ECP "ECP::Point" or \ref EC2N "EC2N::Point" +/// \brief Base class for a Discrete Log (DL) key +/// \tparam T class or type of an element +/// \details The element is usually an Integer, \ref ECP "ECP::Point" or \ref EC2N "EC2N::Point" template class CRYPTOPP_NO_VTABLE DL_Key { public: virtual ~DL_Key() {} - //! \brief Retrieves abstract group parameters - //! \return a const reference to the group parameters + /// \brief Retrieves abstract group parameters + /// \return a const reference to the group parameters virtual const DL_GroupParameters & GetAbstractGroupParameters() const =0; - //! \brief Retrieves abstract group parameters - //! \return a non-const reference to the group parameters + /// \brief Retrieves abstract group parameters + /// \return a non-const reference to the group parameters virtual DL_GroupParameters & AccessAbstractGroupParameters() =0; }; -//! \brief Interface for Discrete Log (DL) public keys +/// \brief Interface for Discrete Log (DL) public keys template class CRYPTOPP_NO_VTABLE DL_PublicKey : public DL_Key { @@ -1047,65 +1047,65 @@ public: virtual ~DL_PublicKey(); - //! \brief Get a named value - //! \param name the name of the object or value to retrieve - //! \param valueType reference to a variable that receives the value - //! \param pValue void pointer to a variable that receives the value - //! \returns true if the value was retrieved, false otherwise - //! \details GetVoidValue() retrieves the value of name if it exists. - //! \note GetVoidValue() is an internal function and should be implemented - //! by derived classes. Users should use one of the other functions instead. - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Get a named value + /// \param name the name of the object or value to retrieve + /// \param valueType reference to a variable that receives the value + /// \param pValue void pointer to a variable that receives the value + /// \returns true if the value was retrieved, false otherwise + /// \details GetVoidValue() retrieves the value of name if it exists. + /// \note GetVoidValue() is an internal function and should be implemented + /// by derived classes. Users should use one of the other functions instead. + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() bool GetVoidValue(const char *name, const std::type_info &valueType, void *pValue) const { return GetValueHelper(this, name, valueType, pValue, &this->GetAbstractGroupParameters()) CRYPTOPP_GET_FUNCTION_ENTRY(PublicElement); } - //! \brief Initialize or reinitialize this this key - //! \param source NameValuePairs to assign + /// \brief Initialize or reinitialize this this key + /// \param source NameValuePairs to assign void AssignFrom(const NameValuePairs &source); - //! \brief Retrieves the public element - //! \returns the public element + /// \brief Retrieves the public element + /// \returns the public element virtual const Element & GetPublicElement() const {return GetPublicPrecomputation().GetBase(this->GetAbstractGroupParameters().GetGroupPrecomputation());} - //! \brief Sets the public element - //! \param y the public element + /// \brief Sets the public element + /// \param y the public element virtual void SetPublicElement(const Element &y) {AccessPublicPrecomputation().SetBase(this->GetAbstractGroupParameters().GetGroupPrecomputation(), y);} - //! \brief Exponentiates this element - //! \param exponent the exponent to raise the base - //! \returns the public element raised to the exponent + /// \brief Exponentiates this element + /// \param exponent the exponent to raise the base + /// \returns the public element raised to the exponent virtual Element ExponentiatePublicElement(const Integer &exponent) const { const DL_GroupParameters ¶ms = this->GetAbstractGroupParameters(); return GetPublicPrecomputation().Exponentiate(params.GetGroupPrecomputation(), exponent); } - //! \brief Exponentiates an element - //! \param baseExp the first exponent - //! \param publicExp the second exponent - //! \returns the public element raised to the exponent - //! \details CascadeExponentiateBaseAndPublicElement raises the public element to - //! the base element and precomputation. + /// \brief Exponentiates an element + /// \param baseExp the first exponent + /// \param publicExp the second exponent + /// \returns the public element raised to the exponent + /// \details CascadeExponentiateBaseAndPublicElement raises the public element to + /// the base element and precomputation. virtual Element CascadeExponentiateBaseAndPublicElement(const Integer &baseExp, const Integer &publicExp) const { const DL_GroupParameters ¶ms = this->GetAbstractGroupParameters(); return params.GetBasePrecomputation().CascadeExponentiate(params.GetGroupPrecomputation(), baseExp, GetPublicPrecomputation(), publicExp); } - //! \brief Accesses the public precomputation - //! \details GetPublicPrecomputation returns a const reference, while - //! AccessPublicPrecomputation returns a non-const reference. Must be - //! overridden in derived classes. + /// \brief Accesses the public precomputation + /// \details GetPublicPrecomputation returns a const reference, while + /// AccessPublicPrecomputation returns a non-const reference. Must be + /// overridden in derived classes. virtual const DL_FixedBasePrecomputation & GetPublicPrecomputation() const =0; - //! \brief Accesses the public precomputation - //! \details GetPublicPrecomputation returns a const reference, while - //! AccessPublicPrecomputation returns a non-const reference. Must be - //! overridden in derived classes. + /// \brief Accesses the public precomputation + /// \details GetPublicPrecomputation returns a const reference, while + /// AccessPublicPrecomputation returns a non-const reference. Must be + /// overridden in derived classes. virtual DL_FixedBasePrecomputation & AccessPublicPrecomputation() =0; }; @@ -1113,7 +1113,7 @@ public: template DL_PublicKey::~DL_PublicKey() {} -//! \brief Interface for Discrete Log (DL) private keys +/// \brief Interface for Discrete Log (DL) private keys template class CRYPTOPP_NO_VTABLE DL_PrivateKey : public DL_Key { @@ -1124,32 +1124,32 @@ public: virtual ~DL_PrivateKey(); - //! \brief Initializes a public key from this key - //! \param pub reference to a public key + /// \brief Initializes a public key from this key + /// \param pub reference to a public key void MakePublicKey(DL_PublicKey &pub) const { pub.AccessAbstractGroupParameters().AssignFrom(this->GetAbstractGroupParameters()); pub.SetPublicElement(this->GetAbstractGroupParameters().ExponentiateBase(GetPrivateExponent())); } - //! \brief Get a named value - //! \param name the name of the object or value to retrieve - //! \param valueType reference to a variable that receives the value - //! \param pValue void pointer to a variable that receives the value - //! \returns true if the value was retrieved, false otherwise - //! \details GetVoidValue() retrieves the value of name if it exists. - //! \note GetVoidValue() is an internal function and should be implemented - //! by derived classes. Users should use one of the other functions instead. - //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), - //! GetRequiredParameter() and GetRequiredIntParameter() + /// \brief Get a named value + /// \param name the name of the object or value to retrieve + /// \param valueType reference to a variable that receives the value + /// \param pValue void pointer to a variable that receives the value + /// \returns true if the value was retrieved, false otherwise + /// \details GetVoidValue() retrieves the value of name if it exists. + /// \note GetVoidValue() is an internal function and should be implemented + /// by derived classes. Users should use one of the other functions instead. + /// \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), + /// GetRequiredParameter() and GetRequiredIntParameter() bool GetVoidValue(const char *name, const std::type_info &valueType, void *pValue) const { return GetValueHelper(this, name, valueType, pValue, &this->GetAbstractGroupParameters()) CRYPTOPP_GET_FUNCTION_ENTRY(PrivateExponent); } - //! \brief Initialize or reinitialize this this key - //! \param source NameValuePairs to assign + /// \brief Initialize or reinitialize this this key + /// \param source NameValuePairs to assign void AssignFrom(const NameValuePairs &source) { this->AccessAbstractGroupParameters().AssignFrom(source); @@ -1157,13 +1157,13 @@ public: CRYPTOPP_SET_FUNCTION_ENTRY(PrivateExponent); } - //! \brief Retrieves the private exponent - //! \returns the private exponent - //! \details Must be overridden in derived classes. + /// \brief Retrieves the private exponent + /// \returns the private exponent + /// \details Must be overridden in derived classes. virtual const Integer & GetPrivateExponent() const =0; - //! \brief Sets the private exponent - //! \param x the private exponent - //! \details Must be overridden in derived classes. + /// \brief Sets the private exponent + /// \param x the private exponent + /// \details Must be overridden in derived classes. virtual void SetPrivateExponent(const Integer &x) =0; }; @@ -1187,7 +1187,7 @@ void DL_PublicKey::AssignFrom(const NameValuePairs &source) class OID; -//! \brief Discrete Log (DL) key base implementation +/// \brief Discrete Log (DL) key base implementation template class DL_KeyImpl : public PK { @@ -1212,7 +1212,7 @@ private: class X509PublicKey; class PKCS8PrivateKey; -//! \brief Discrete Log (DL) private key base implementation +/// \brief Discrete Log (DL) private key base implementation template class DL_PrivateKeyImpl : public DL_PrivateKey, public DL_KeyImpl { @@ -1282,7 +1282,7 @@ private: Integer m_x; }; -//! _ +/// _ template class DL_PrivateKey_WithSignaturePairwiseConsistencyTest : public BASE { @@ -1302,7 +1302,7 @@ public: } }; -//! \brief Discrete Log (DL) public key base implementation +/// \brief Discrete Log (DL) public key base implementation template class DL_PublicKeyImpl : public DL_PublicKey, public DL_KeyImpl { @@ -1369,7 +1369,7 @@ private: template DL_PublicKeyImpl::~DL_PublicKeyImpl() {} -//! \brief Interface for Elgamal-like signature algorithms +/// \brief Interface for Elgamal-like signature algorithms template class CRYPTOPP_NO_VTABLE DL_ElgamalLikeSignatureAlgorithm { @@ -1393,8 +1393,8 @@ public: {return false;} }; -//! \brief Interface for deterministic signers -//! \details RFC 6979 signers which generate k based on the encoded message and private key +/// \brief Interface for deterministic signers +/// \details RFC 6979 signers which generate k based on the encoded message and private key class CRYPTOPP_NO_VTABLE DeterministicSignatureAlgorithm { public: @@ -1403,7 +1403,7 @@ public: virtual Integer GenerateRandom(const Integer &x, const Integer &q, const Integer &e) const =0; }; -//! \brief Interface for DL key agreement algorithms +/// \brief Interface for DL key agreement algorithms template class CRYPTOPP_NO_VTABLE DL_KeyAgreementAlgorithm { @@ -1416,7 +1416,7 @@ public: virtual Element AgreeWithStaticPrivateKey(const DL_GroupParameters ¶ms, const Element &publicElement, bool validateOtherPublicKey, const Integer &privateExponent) const =0; }; -//! \brief Interface for key derivation algorithms used in DL cryptosystems +/// \brief Interface for key derivation algorithms used in DL cryptosystems template class CRYPTOPP_NO_VTABLE DL_KeyDerivationAlgorithm { @@ -1428,7 +1428,7 @@ public: virtual void Derive(const DL_GroupParameters &groupParams, byte *derivedKey, size_t derivedLength, const T &agreedElement, const T &ephemeralPublicKey, const NameValuePairs &derivationParams) const =0; }; -//! \brief Interface for symmetric encryption algorithms used in DL cryptosystems +/// \brief Interface for symmetric encryption algorithms used in DL cryptosystems class CRYPTOPP_NO_VTABLE DL_SymmetricEncryptionAlgorithm { public: @@ -1443,8 +1443,8 @@ public: virtual DecodingResult SymmetricDecrypt(const byte *key, const byte *ciphertext, size_t ciphertextLength, byte *plaintext, const NameValuePairs ¶meters) const =0; }; -//! \brief Discrete Log (DL) base interface -//! \tparam KI public or private key interface +/// \brief Discrete Log (DL) base interface +/// \tparam KI public or private key interface template class CRYPTOPP_NO_VTABLE DL_Base { @@ -1461,50 +1461,50 @@ protected: virtual const KeyInterface & GetKeyInterface() const =0; }; -//! \brief Discrete Log (DL) signature scheme base implementation -//! \tparam INTFACE PK_Signer or PK_Verifier derived class -//! \tparam KEY_INTFACE DL_Base key base used in the scheme -//! \details DL_SignatureSchemeBase provides common functions for signers and verifiers. -//! DL_Base is used for signers, and DL_Base is used for verifiers. +/// \brief Discrete Log (DL) signature scheme base implementation +/// \tparam INTFACE PK_Signer or PK_Verifier derived class +/// \tparam KEY_INTFACE DL_Base key base used in the scheme +/// \details DL_SignatureSchemeBase provides common functions for signers and verifiers. +/// DL_Base is used for signers, and DL_Base is used for verifiers. template class CRYPTOPP_NO_VTABLE DL_SignatureSchemeBase : public INTFACE, public DL_Base { public: virtual ~DL_SignatureSchemeBase() {} - //! \brief Provides the signature length - //! \returns signature length, in bytes - //! \details SignatureLength returns the size required for r+s. + /// \brief Provides the signature length + /// \returns signature length, in bytes + /// \details SignatureLength returns the size required for r+s. size_t SignatureLength() const { return GetSignatureAlgorithm().RLen(this->GetAbstractGroupParameters()) + GetSignatureAlgorithm().SLen(this->GetAbstractGroupParameters()); } - //! \brief Provides the maximum recoverable length - //! \returns maximum recoverable length, in bytes + /// \brief Provides the maximum recoverable length + /// \returns maximum recoverable length, in bytes size_t MaxRecoverableLength() const {return GetMessageEncodingInterface().MaxRecoverableLength(0, GetHashIdentifier().second, GetDigestSize());} - //! \brief Provides the maximum recoverable length - //! \param signatureLength the size fo the signature - //! \returns maximum recoverable length based on signature length, in bytes - //! \details this function is not implemented and always returns 0. + /// \brief Provides the maximum recoverable length + /// \param signatureLength the size fo the signature + /// \returns maximum recoverable length based on signature length, in bytes + /// \details this function is not implemented and always returns 0. size_t MaxRecoverableLengthFromSignatureLength(size_t signatureLength) const {CRYPTOPP_UNUSED(signatureLength); CRYPTOPP_ASSERT(false); return 0;} // TODO - //! \brief Determines if the scheme is probabilistic - //! \returns true if the scheme is probabilistic, false otherwise + /// \brief Determines if the scheme is probabilistic + /// \returns true if the scheme is probabilistic, false otherwise bool IsProbabilistic() const {return true;} - //! \brief Determines if the scheme has non-recoverable part - //! \returns true if the message encoding has a non-recoverable part, false otherwise. + /// \brief Determines if the scheme has non-recoverable part + /// \returns true if the message encoding has a non-recoverable part, false otherwise. bool AllowNonrecoverablePart() const {return GetMessageEncodingInterface().AllowNonrecoverablePart();} - //! \brief Determines if the scheme allows recoverable part first - //! \returns true if the message encoding allows the recoverable part, false otherwise. + /// \brief Determines if the scheme allows recoverable part first + /// \returns true if the message encoding allows the recoverable part, false otherwise. bool RecoverablePartFirst() const {return GetMessageEncodingInterface().RecoverablePartFirst();} @@ -1521,19 +1521,19 @@ protected: virtual size_t GetDigestSize() const =0; }; -//! \brief Discrete Log (DL) signature scheme signer base implementation -//! \tparam T class or type +/// \brief Discrete Log (DL) signature scheme signer base implementation +/// \tparam T class or type template class CRYPTOPP_NO_VTABLE DL_SignerBase : public DL_SignatureSchemeBase > { public: virtual ~DL_SignerBase() {} - //! \brief Testing interface - //! \param k Integer - //! \param e Integer - //! \param r Integer - //! \param s Integer + /// \brief Testing interface + /// \param k Integer + /// \param e Integer + /// \param r Integer + /// \param s Integer void RawSign(const Integer &k, const Integer &e, Integer &r, Integer &s) const { const DL_ElgamalLikeSignatureAlgorithm &alg = this->GetSignatureAlgorithm(); @@ -1631,7 +1631,7 @@ protected: } }; -//! _ +/// _ template class CRYPTOPP_NO_VTABLE DL_VerifierBase : public DL_SignatureSchemeBase > { @@ -1702,9 +1702,9 @@ public: } }; -//! \brief Discrete Log (DL) cryptosystem base implementation -//! \tparam PK field element type -//! \tparam KI public or private key interface +/// \brief Discrete Log (DL) cryptosystem base implementation +/// \tparam PK field element type +/// \tparam KI public or private key interface template class CRYPTOPP_NO_VTABLE DL_CryptoSystemBase : public PK, public DL_Base { @@ -1734,8 +1734,8 @@ protected: virtual const DL_SymmetricEncryptionAlgorithm & GetSymmetricEncryptionAlgorithm() const =0; }; -//! \brief Discrete Log (DL) decryptor base implementation -//! \tparam T field element type +/// \brief Discrete Log (DL) decryptor base implementation +/// \tparam T field element type template class CRYPTOPP_NO_VTABLE DL_DecryptorBase : public DL_CryptoSystemBase > { @@ -1774,8 +1774,8 @@ public: } }; -//! \brief Discrete Log (DL) encryptor base implementation -//! \tparam T field element type +/// \brief Discrete Log (DL) encryptor base implementation +/// \tparam T field element type template class CRYPTOPP_NO_VTABLE DL_EncryptorBase : public DL_CryptoSystemBase > { @@ -1807,9 +1807,9 @@ public: } }; -//! \brief Discrete Log (DL) scheme options -//! \tparam T1 algorithm information -//! \tparam T2 group parameters for the scheme +/// \brief Discrete Log (DL) scheme options +/// \tparam T1 algorithm information +/// \tparam T2 group parameters for the scheme template struct DL_SchemeOptionsBase { @@ -1818,9 +1818,9 @@ struct DL_SchemeOptionsBase typedef typename GroupParameters::Element Element; }; -//! \brief Discrete Log (DL) key options -//! \tparam T1 algorithm information -//! \tparam T2 keys used in the scheme +/// \brief Discrete Log (DL) key options +/// \tparam T1 algorithm information +/// \tparam T2 keys used in the scheme template struct DL_KeyedSchemeOptions : public DL_SchemeOptionsBase { @@ -1829,12 +1829,12 @@ struct DL_KeyedSchemeOptions : public DL_SchemeOptionsBase struct DL_SignatureSchemeOptions : public DL_KeyedSchemeOptions { @@ -1843,12 +1843,12 @@ struct DL_SignatureSchemeOptions : public DL_KeyedSchemeOptions typedef T5 HashFunction; }; -//! \brief Discrete Log (DL) crypto scheme options -//! \tparam T1 algorithm information -//! \tparam T2 keys used in the scheme -//! \tparam T3 key agreement algorithm -//! \tparam T4 key derivation algorithm -//! \tparam T5 symmetric encryption algorithm +/// \brief Discrete Log (DL) crypto scheme options +/// \tparam T1 algorithm information +/// \tparam T2 keys used in the scheme +/// \tparam T3 key agreement algorithm +/// \tparam T4 key derivation algorithm +/// \tparam T5 symmetric encryption algorithm template struct DL_CryptoSchemeOptions : public DL_KeyedSchemeOptions { @@ -1857,10 +1857,10 @@ struct DL_CryptoSchemeOptions : public DL_KeyedSchemeOptions typedef T5 SymmetricEncryptionAlgorithm; }; -//! \brief Discrete Log (DL) base object implementation -//! \tparam BASE TODO -//! \tparam SCHEME_OPTIONS options for the scheme -//! \tparam KEY key used in the scheme +/// \brief Discrete Log (DL) base object implementation +/// \tparam BASE TODO +/// \tparam SCHEME_OPTIONS options for the scheme +/// \tparam KEY key used in the scheme template class CRYPTOPP_NO_VTABLE DL_ObjectImplBase : public AlgorithmImpl { @@ -1897,10 +1897,10 @@ private: KEY m_key; }; -//! \brief Discrete Log (DL) object implementation -//! \tparam BASE TODO -//! \tparam SCHEME_OPTIONS options for the scheme -//! \tparam KEY key used in the scheme +/// \brief Discrete Log (DL) object implementation +/// \tparam BASE TODO +/// \tparam SCHEME_OPTIONS options for the scheme +/// \tparam KEY key used in the scheme template class CRYPTOPP_NO_VTABLE DL_ObjectImpl : public DL_ObjectImplBase { @@ -1924,8 +1924,8 @@ protected: {return Singleton().Ref();} }; -//! \brief Discrete Log (DL) signer implementation -//! \tparam SCHEME_OPTIONS options for the scheme +/// \brief Discrete Log (DL) signer implementation +/// \tparam SCHEME_OPTIONS options for the scheme template class DL_SignerImpl : public DL_ObjectImpl, SCHEME_OPTIONS, typename SCHEME_OPTIONS::PrivateKey> { @@ -1938,8 +1938,8 @@ public: } }; -//! \brief Discrete Log (DL) verifier implementation -//! \tparam SCHEME_OPTIONS options for the scheme +/// \brief Discrete Log (DL) verifier implementation +/// \tparam SCHEME_OPTIONS options for the scheme template class DL_VerifierImpl : public DL_ObjectImpl, SCHEME_OPTIONS, typename SCHEME_OPTIONS::PublicKey> { @@ -1950,15 +1950,15 @@ public: } }; -//! \brief Discrete Log (DL) encryptor implementation -//! \tparam SCHEME_OPTIONS options for the scheme +/// \brief Discrete Log (DL) encryptor implementation +/// \tparam SCHEME_OPTIONS options for the scheme template class DL_EncryptorImpl : public DL_ObjectImpl, SCHEME_OPTIONS, typename SCHEME_OPTIONS::PublicKey> { }; -//! \brief Discrete Log (DL) decryptor implementation -//! \tparam SCHEME_OPTIONS options for the scheme +/// \brief Discrete Log (DL) decryptor implementation +/// \tparam SCHEME_OPTIONS options for the scheme template class DL_DecryptorImpl : public DL_ObjectImpl, SCHEME_OPTIONS, typename SCHEME_OPTIONS::PrivateKey> { @@ -1966,8 +1966,8 @@ class DL_DecryptorImpl : public DL_ObjectImpl class CRYPTOPP_NO_VTABLE DL_SimpleKeyAgreementDomainBase : public SimpleKeyAgreementDomain { @@ -2015,8 +2015,8 @@ public: return true; } - //! \brief Retrieves a reference to the group generator - //! \returns const reference to the group generator + /// \brief Retrieves a reference to the group generator + /// \returns const reference to the group generator const Element &GetGenerator() const {return GetAbstractGroupParameters().GetSubgroupGenerator();} protected: @@ -2025,27 +2025,27 @@ protected: const DL_GroupParameters & GetAbstractGroupParameters() const {return const_cast *>(this)->AccessAbstractGroupParameters();} }; -//! \brief Methods for avoiding "Small-Subgroup" attacks on Diffie-Hellman Key Agreement -//! \details Additional methods exist and include public key validation and choice of prime p. -//! \sa Methods for Avoiding the "Small-Subgroup" Attacks on the -//! Diffie-Hellman Key Agreement Method for S/MIME +/// \brief Methods for avoiding "Small-Subgroup" attacks on Diffie-Hellman Key Agreement +/// \details Additional methods exist and include public key validation and choice of prime p. +/// \sa Methods for Avoiding the "Small-Subgroup" Attacks on the +/// Diffie-Hellman Key Agreement Method for S/MIME enum CofactorMultiplicationOption { - //! \brief No cofactor multiplication applied + /// \brief No cofactor multiplication applied NO_COFACTOR_MULTIPLICTION, - //! \brief Cofactor multiplication compatible with ordinary Diffie-Hellman - //! \details Modifies the computation of ZZ by including j (the cofactor) in the computations and is - //! compatible with ordinary Diffie-Hellman. + /// \brief Cofactor multiplication compatible with ordinary Diffie-Hellman + /// \details Modifies the computation of ZZ by including j (the cofactor) in the computations and is + /// compatible with ordinary Diffie-Hellman. COMPATIBLE_COFACTOR_MULTIPLICTION, - //! \brief Cofactor multiplication incompatible with ordinary Diffie-Hellman - //! \details Modifies the computation of ZZ by including j (the cofactor) in the computations but is - //! not compatible with ordinary Diffie-Hellman. + /// \brief Cofactor multiplication incompatible with ordinary Diffie-Hellman + /// \details Modifies the computation of ZZ by including j (the cofactor) in the computations but is + /// not compatible with ordinary Diffie-Hellman. INCOMPATIBLE_COFACTOR_MULTIPLICTION}; typedef EnumToType NoCofactorMultiplication; typedef EnumToType CompatibleCofactorMultiplication; typedef EnumToType IncompatibleCofactorMultiplication; -//! \brief Diffie-Hellman key agreement algorithm +/// \brief Diffie-Hellman key agreement algorithm template class DL_KeyAgreementAlgorithm_DH : public DL_KeyAgreementAlgorithm { @@ -2101,7 +2101,7 @@ public: // ******************************************************** -//! \brief Template implementing constructors for public key algorithm classes +/// \brief Template implementing constructors for public key algorithm classes template class CRYPTOPP_NO_VTABLE PK_FinalTemplate : public BASE { @@ -2177,20 +2177,20 @@ public: {this->AccessKey().Initialize(v1, v2, v3, v4, v5, v6, v7, v8);} }; -//! \brief Base class for public key encryption standard classes. -//! \details These classes are used to select from variants of algorithms. -//! Not all standards apply to all algorithms. +/// \brief Base class for public key encryption standard classes. +/// \details These classes are used to select from variants of algorithms. +/// Not all standards apply to all algorithms. struct EncryptionStandard {}; -//! \brief Base class for public key signature standard classes. -//! \details These classes are used to select from variants of algorithms. -//! Not all standards apply to all algorithms. +/// \brief Base class for public key signature standard classes. +/// \details These classes are used to select from variants of algorithms. +/// Not all standards apply to all algorithms. struct SignatureStandard {}; -//! \brief Trapdoor Function (TF) encryption scheme -//! \tparam STANDARD standard -//! \tparam KEYS keys used in the encryption scheme -//! \tparam ALG_INFO algorithm information +/// \brief Trapdoor Function (TF) encryption scheme +/// \tparam STANDARD standard +/// \tparam KEYS keys used in the encryption scheme +/// \tparam ALG_INFO algorithm information template class TF_ES; @@ -2200,24 +2200,24 @@ class TF_ES : public KEYS typedef typename STANDARD::EncryptionMessageEncodingMethod MessageEncodingMethod; public: - //! see EncryptionStandard for a list of standards + /// see EncryptionStandard for a list of standards typedef STANDARD Standard; typedef TF_CryptoSchemeOptions SchemeOptions; static std::string CRYPTOPP_API StaticAlgorithmName() {return std::string(KEYS::StaticAlgorithmName()) + "/" + MessageEncodingMethod::StaticAlgorithmName();} - //! implements PK_Decryptor interface + /// implements PK_Decryptor interface typedef PK_FinalTemplate > Decryptor; - //! implements PK_Encryptor interface + /// implements PK_Encryptor interface typedef PK_FinalTemplate > Encryptor; }; -//! \class TF_SS -//! \brief Trapdoor Function (TF) Signature Scheme -//! \tparam STANDARD standard -//! \tparam H hash function -//! \tparam KEYS keys used in the signature scheme -//! \tparam ALG_INFO algorithm information +/// \class TF_SS +/// \brief Trapdoor Function (TF) Signature Scheme +/// \tparam STANDARD standard +/// \tparam H hash function +/// \tparam KEYS keys used in the signature scheme +/// \tparam ALG_INFO algorithm information template class TF_SS; @@ -2225,26 +2225,26 @@ template SchemeOptions; static std::string CRYPTOPP_API StaticAlgorithmName() {return std::string(KEYS::StaticAlgorithmName()) + "/" + MessageEncodingMethod::StaticAlgorithmName() + "(" + H::StaticAlgorithmName() + ")";} - //! implements PK_Signer interface + /// implements PK_Signer interface typedef PK_FinalTemplate > Signer; - //! implements PK_Verifier interface + /// implements PK_Verifier interface typedef PK_FinalTemplate > Verifier; }; -//! \class DL_SS -//! \brief Discrete Log (DL) signature scheme -//! \tparam KEYS keys used in the signature scheme -//! \tparam SA signature algorithm -//! \tparam MEM message encoding method -//! \tparam H hash function -//! \tparam ALG_INFO algorithm information +/// \class DL_SS +/// \brief Discrete Log (DL) signature scheme +/// \tparam KEYS keys used in the signature scheme +/// \tparam SA signature algorithm +/// \tparam MEM message encoding method +/// \tparam H hash function +/// \tparam ALG_INFO algorithm information template class DL_SS; @@ -2256,27 +2256,27 @@ class DL_SS : public KEYS public: static std::string StaticAlgorithmName() {return SA::StaticAlgorithmName() + std::string("/EMSA1(") + H::StaticAlgorithmName() + ")";} - //! implements PK_Signer interface + /// implements PK_Signer interface typedef PK_FinalTemplate > Signer; - //! implements PK_Verifier interface + /// implements PK_Verifier interface typedef PK_FinalTemplate > Verifier; }; -//! \brief Discrete Log (DL) encryption scheme -//! \tparam KEYS keys used in the encryption scheme -//! \tparam AA key agreement algorithm -//! \tparam DA key derivation algorithm -//! \tparam EA encryption algorithm -//! \tparam ALG_INFO algorithm information +/// \brief Discrete Log (DL) encryption scheme +/// \tparam KEYS keys used in the encryption scheme +/// \tparam AA key agreement algorithm +/// \tparam DA key derivation algorithm +/// \tparam EA encryption algorithm +/// \tparam ALG_INFO algorithm information template class DL_ES : public KEYS { typedef DL_CryptoSchemeOptions SchemeOptions; public: - //! implements PK_Decryptor interface + /// implements PK_Decryptor interface typedef PK_FinalTemplate > Decryptor; - //! implements PK_Encryptor interface + /// implements PK_Encryptor interface typedef PK_FinalTemplate > Encryptor; }; diff --git a/pwdbased.h b/pwdbased.h index 1bb323d6..7d5f79e0 100644 --- a/pwdbased.h +++ b/pwdbased.h @@ -1,7 +1,7 @@ // pwdbased.h - originally written and placed in the public domain by Wei Dai -//! \file pwdbased.h -//! \brief Password based key derivation functions +/// \file pwdbased.h +/// \brief Password based key derivation functions #ifndef CRYPTOPP_PWDBASED_H #define CRYPTOPP_PWDBASED_H @@ -13,39 +13,39 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Abstract base class for password based key derivation function +/// \brief Abstract base class for password based key derivation function class PasswordBasedKeyDerivationFunction { public: virtual ~PasswordBasedKeyDerivationFunction() {} - //! \brief Provides the maximum derived key length - //! \returns maximum derived key length, in bytes + /// \brief Provides the maximum derived key length + /// \returns maximum derived key length, in bytes virtual size_t MaxDerivedKeyLength() const =0; - //! \brief Determines if the derivation function uses the purpose byte - //! \returns true if the derivation function uses the purpose byte, false otherwise + /// \brief Determines if the derivation function uses the purpose byte + /// \returns true if the derivation function uses the purpose byte, false otherwise virtual bool UsesPurposeByte() const =0; - //! \brief Derive key from the password - //! \param derived the byte buffer to receive the derived password - //! \param derivedLen the size of the byte buffer to receive the derived password - //! \param purpose an octet indicating the purpose of the derivation - //! \param password the byte buffer with the password - //! \param passwordLen the size of the password, in bytes - //! \param salt the byte buffer with the salt - //! \param saltLen the size of the salt, in bytes - //! \param iterations the number of iterations to attempt - //! \param timeInSeconds the length of time the derivation function should execute - //! \returns iteration count achieved - //! \details DeriveKey returns the actual iteration count achieved. If timeInSeconds == 0, then the complete number - //! of iterations will be obtained. If timeInSeconds != 0, then DeriveKey will iterate until time elapsed, as - //! measured by ThreadUserTimer. + /// \brief Derive key from the password + /// \param derived the byte buffer to receive the derived password + /// \param derivedLen the size of the byte buffer to receive the derived password + /// \param purpose an octet indicating the purpose of the derivation + /// \param password the byte buffer with the password + /// \param passwordLen the size of the password, in bytes + /// \param salt the byte buffer with the salt + /// \param saltLen the size of the salt, in bytes + /// \param iterations the number of iterations to attempt + /// \param timeInSeconds the length of time the derivation function should execute + /// \returns iteration count achieved + /// \details DeriveKey returns the actual iteration count achieved. If timeInSeconds == 0, then the complete number + /// of iterations will be obtained. If timeInSeconds != 0, then DeriveKey will iterate until time elapsed, as + /// measured by ThreadUserTimer. virtual unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds=0) const =0; }; -//! \brief PBKDF1 from PKCS #5 -//! \tparam T a HashTransformation class +/// \brief PBKDF1 from PKCS #5 +/// \tparam T a HashTransformation class template class PKCS5_PBKDF1 : public PasswordBasedKeyDerivationFunction { @@ -56,8 +56,8 @@ public: unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds=0) const; }; -//! \brief PBKDF2 from PKCS #5 -//! \tparam T a HashTransformation class +/// \brief PBKDF2 from PKCS #5 +/// \tparam T a HashTransformation class template class PKCS5_PBKDF2_HMAC : public PasswordBasedKeyDerivationFunction { @@ -167,8 +167,8 @@ unsigned int PKCS5_PBKDF2_HMAC::DeriveKey(byte *derived, size_t derivedLen, b return iterations; } -//! \brief PBKDF from PKCS #12, appendix B -//! \tparam T a HashTransformation class +/// \brief PBKDF from PKCS #12, appendix B +/// \tparam T a HashTransformation class template class PKCS12_PBKDF : public PasswordBasedKeyDerivationFunction { diff --git a/queue.h b/queue.h index c9c9f76f..40ebb47b 100644 --- a/queue.h +++ b/queue.h @@ -1,7 +1,7 @@ // queue.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \brief Classes for an unlimited queue to store bytes +/// \file +/// \brief Classes for an unlimited queue to store bytes #ifndef CRYPTOPP_QUEUE_H #define CRYPTOPP_QUEUE_H @@ -13,21 +13,21 @@ NAMESPACE_BEGIN(CryptoPP) class ByteQueueNode; -//! \class ByteQueue -//! \brief Data structure used to store byte strings -//! \details The queue is implemented as a linked list of byte arrays +/// \class ByteQueue +/// \brief Data structure used to store byte strings +/// \details The queue is implemented as a linked list of byte arrays class CRYPTOPP_DLL ByteQueue : public Bufferless { public: - //! \brief Construct a ByteQueue - //! \param nodeSize the initial node size - //! \details Internally, ByteQueue uses a ByteQueueNode to store bytes, and \p nodeSize determines the - //! size of the ByteQueueNode. A value of 0 indicates the ByteQueueNode should be automatically sized, - //! which means a value of 256 is used. + /// \brief Construct a ByteQueue + /// \param nodeSize the initial node size + /// \details Internally, ByteQueue uses a ByteQueueNode to store bytes, and \p nodeSize determines the + /// size of the ByteQueueNode. A value of 0 indicates the ByteQueueNode should be automatically sized, + /// which means a value of 256 is used. ByteQueue(size_t nodeSize=0); - //! \brief Copy construct a ByteQueue - //! \param copy the other ByteQueue + /// \brief Copy construct a ByteQueue + /// \param copy the other ByteQueue ByteQueue(const ByteQueue ©); ~ByteQueue(); @@ -73,13 +73,13 @@ public: byte operator[](lword i) const; void swap(ByteQueue &rhs); - //! \class Walker - //! \brief A ByteQueue iterator + /// \class Walker + /// \brief A ByteQueue iterator class Walker : public InputRejecting { public: - //! \brief Construct a ByteQueue Walker - //! \param queue a ByteQueue + /// \brief Construct a ByteQueue Walker + /// \param queue a ByteQueue Walker(const ByteQueue &queue) : m_queue(queue), m_node(NULLPTR), m_position(0), m_offset(0), m_lazyString(NULLPTR), m_lazyLength(0) {Initialize();} @@ -124,7 +124,7 @@ private: bool m_lazyStringModifiable; }; -//! use this to make sure LazyPut is finalized in event of exception +/// use this to make sure LazyPut is finalized in event of exception class CRYPTOPP_DLL LazyPutter { public: @@ -138,7 +138,7 @@ private: ByteQueue &m_bq; }; -//! like LazyPutter, but does a LazyPutModifiable instead +/// like LazyPutter, but does a LazyPutModifiable instead class LazyPutterModifiable : public LazyPutter { public: diff --git a/rabin.h b/rabin.h index 30c5b69a..ad476ea3 100644 --- a/rabin.h +++ b/rabin.h @@ -1,7 +1,7 @@ // rabin.h - originally written and placed in the public domain by Wei Dai -//! \file rabin.h -//! \brief Classes for Rabin encryption and signature schemes +/// \file rabin.h +/// \brief Classes for Rabin encryption and signature schemes #ifndef CRYPTOPP_RABIN_H #define CRYPTOPP_RABIN_H @@ -13,19 +13,19 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RabinFunction -//! \brief Rabin trapdoor function using the public key -//! \since Crypto++ 2.0 +/// \class RabinFunction +/// \brief Rabin trapdoor function using the public key +/// \since Crypto++ 2.0 class RabinFunction : public TrapdoorFunction, public PublicKey { typedef RabinFunction ThisClass; public: - //! \brief Initialize a Rabin public key - //! \param n the modulus - //! \param r element r - //! \param s element s + /// \brief Initialize a Rabin public key + /// \param n the modulus + /// \param r element r + /// \param s element s void Initialize(const Integer &n, const Integer &r, const Integer &s) {m_n = n; m_r = r; m_s = s;} @@ -52,32 +52,32 @@ protected: Integer m_n, m_r, m_s; }; -//! \class InvertibleRabinFunction -//! \brief Rabin trapdoor function using the private key -//! \since Crypto++ 2.0 +/// \class InvertibleRabinFunction +/// \brief Rabin trapdoor function using the private key +/// \since Crypto++ 2.0 class InvertibleRabinFunction : public RabinFunction, public TrapdoorFunctionInverse, public PrivateKey { typedef InvertibleRabinFunction ThisClass; public: - //! \brief Initialize a Rabin private key - //! \param n modulus - //! \param r element r - //! \param s element s - //! \param p first prime factor - //! \param q second prime factor - //! \param u q-1 mod p - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize a Rabin private key + /// \param n modulus + /// \param r element r + /// \param s element s + /// \param p first prime factor + /// \param q second prime factor + /// \param u q-1 mod p + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const Integer &n, const Integer &r, const Integer &s, const Integer &p, const Integer &q, const Integer &u) {m_n = n; m_r = r; m_s = s; m_p = p; m_q = q; m_u = u;} - //! \brief Create a Rabin private key - //! \param rng a RandomNumberGenerator derived class - //! \param keybits the size of the key, in bits - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a Rabin private key + /// \param rng a RandomNumberGenerator derived class + /// \param keybits the size of the key, in bits + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int keybits) {GenerateRandomWithKeySize(rng, keybits);} @@ -104,7 +104,7 @@ protected: Integer m_p, m_q, m_u; }; -//! \brief Rabin keys +/// \brief Rabin keys struct Rabin { static std::string StaticAlgorithmName() {return "Rabin-Crypto++Variant";} @@ -112,16 +112,16 @@ struct Rabin typedef InvertibleRabinFunction PrivateKey; }; -//! \brief Rabin encryption scheme -//! \tparam STANDARD encryption standard +/// \brief Rabin encryption scheme +/// \tparam STANDARD encryption standard template struct RabinES : public TF_ES { }; -//! \brief Rabin signature scheme -//! \tparam STANDARD signature standard -//! \tparam H hash transformation +/// \brief Rabin signature scheme +/// \tparam STANDARD signature standard +/// \tparam H hash transformation template struct RabinSS : public TF_SS { diff --git a/randpool.h b/randpool.h index 248c004f..fafad343 100644 --- a/randpool.h +++ b/randpool.h @@ -1,19 +1,19 @@ // randpool.h - originally written and placed in the public domain by Wei Dai // OldRandPool added by JW in August, 2017. -//! \file randpool.h -//! \brief Class file for Randomness Pool -//! \details RandomPool can be used to generate cryptographic quality pseudorandom bytes -//! after seeding the pool with IncorporateEntropy(). Internally, the generator uses -//! AES-256 to produce the stream. Entropy is stirred in using SHA-256. -//! \details RandomPool used to follow the design of randpool in PGP 2.6.x. At version 5.5 -//! RandomPool was redesigned to reduce the risk of reusing random numbers after state -//! rollback (which may occur when running in a virtual machine like VMware or a hosted -//! environment). -//! \details If you need the pre-Crypto++ 5.5 generator then use OldRandomPool class. You -//! should migrate away from OldRandomPool at the earliest opportunity. Use RandomPool -//! or AutoSeededRandomPool instead. -//! \since Crypto++ 4.0 (PGP 2.6.x style), Crypto++ 5.5 (AES-256 based) +/// \file randpool.h +/// \brief Class file for Randomness Pool +/// \details RandomPool can be used to generate cryptographic quality pseudorandom bytes +/// after seeding the pool with IncorporateEntropy(). Internally, the generator uses +/// AES-256 to produce the stream. Entropy is stirred in using SHA-256. +/// \details RandomPool used to follow the design of randpool in PGP 2.6.x. At version 5.5 +/// RandomPool was redesigned to reduce the risk of reusing random numbers after state +/// rollback (which may occur when running in a virtual machine like VMware or a hosted +/// environment). +/// \details If you need the pre-Crypto++ 5.5 generator then use OldRandomPool class. You +/// should migrate away from OldRandomPool at the earliest opportunity. Use RandomPool +/// or AutoSeededRandomPool instead. +/// \since Crypto++ 4.0 (PGP 2.6.x style), Crypto++ 5.5 (AES-256 based) #ifndef CRYPTOPP_RANDPOOL_H #define CRYPTOPP_RANDPOOL_H @@ -26,23 +26,23 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RandomPool -//! \brief Randomness Pool based on AES-256 -//! \details RandomPool can be used to generate cryptographic quality pseudorandom bytes -//! after seeding the pool with IncorporateEntropy(). Internally, the generator uses -//! AES-256 to produce the stream. Entropy is stirred in using SHA-256. -//! \details RandomPool used to follow the design of randpool in PGP 2.6.x. At version 5.5 -//! RandomPool was redesigned to reduce the risk of reusing random numbers after state -//! rollback, which may occur when running in a virtual machine like VMware or a hosted -//! environment. -//! \details If you need the pre-Crypto++ 5.5 generator then use OldRandomPool class. You -//! should migrate away from OldRandomPool at the earliest opportunity. -//! \sa OldRandomPool -//! \since Crypto++ 4.0 (PGP 2.6.x style), Crypto++ 5.5 (AES-256 based) +/// \class RandomPool +/// \brief Randomness Pool based on AES-256 +/// \details RandomPool can be used to generate cryptographic quality pseudorandom bytes +/// after seeding the pool with IncorporateEntropy(). Internally, the generator uses +/// AES-256 to produce the stream. Entropy is stirred in using SHA-256. +/// \details RandomPool used to follow the design of randpool in PGP 2.6.x. At version 5.5 +/// RandomPool was redesigned to reduce the risk of reusing random numbers after state +/// rollback, which may occur when running in a virtual machine like VMware or a hosted +/// environment. +/// \details If you need the pre-Crypto++ 5.5 generator then use OldRandomPool class. You +/// should migrate away from OldRandomPool at the earliest opportunity. +/// \sa OldRandomPool +/// \since Crypto++ 4.0 (PGP 2.6.x style), Crypto++ 5.5 (AES-256 based) class CRYPTOPP_DLL RandomPool : public RandomNumberGenerator, public NotCopyable { public: - //! \brief Construct a RandomPool + /// \brief Construct a RandomPool RandomPool(); bool CanIncorporateEntropy() const {return true;} @@ -56,27 +56,27 @@ private: bool m_keySet; }; -//! \class OldRandomPool -//! \brief Randomness Pool based on PGP 2.6.x with MDC -//! \details If you need the pre-Crypto++ 5.5 generator then use OldRandomPool class. The -//! OldRandomPool class is always available so you dont need to define -//! CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY. OldRandomPool also provides the modern -//! interface, including CanIncorporateEntropy, IncorporateEntropy and -//! GenerateIntoBufferedTransformation. -//! \details You should migrate away from OldRandomPool at the earliest opportunity. Use a -//! modern random number generator or key derivation function, like AutoSeededRandomPool or -//! HKDF. -//! \deprecated This class uses an old style PGP 2.6.x with MDC. The generator risks reusing -//! random random numbers after state rollback. You should migrate away from OldRandomPool -//! at the earliest opportunity. -//! \sa RandomPool, AutoSeededRandomPool, HKDF, P1363_KDF2, PKCS12_PBKDF, PKCS5_PBKDF2_HMAC -//! \since Crypto++ 6.0 (PGP 2.6.x style) +/// \class OldRandomPool +/// \brief Randomness Pool based on PGP 2.6.x with MDC +/// \details If you need the pre-Crypto++ 5.5 generator then use OldRandomPool class. The +/// OldRandomPool class is always available so you dont need to define +/// CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY. OldRandomPool also provides the modern +/// interface, including CanIncorporateEntropy, IncorporateEntropy and +/// GenerateIntoBufferedTransformation. +/// \details You should migrate away from OldRandomPool at the earliest opportunity. Use a +/// modern random number generator or key derivation function, like AutoSeededRandomPool or +/// HKDF. +/// \deprecated This class uses an old style PGP 2.6.x with MDC. The generator risks reusing +/// random random numbers after state rollback. You should migrate away from OldRandomPool +/// at the earliest opportunity. +/// \sa RandomPool, AutoSeededRandomPool, HKDF, P1363_KDF2, PKCS12_PBKDF, PKCS5_PBKDF2_HMAC +/// \since Crypto++ 6.0 (PGP 2.6.x style) class CRYPTOPP_DLL OldRandomPool : public RandomNumberGenerator { public: - //! \brief Construct an OldRandomPool - //! \param poolSize internal pool size of the generator - //! \details poolSize must be greater than 16 + /// \brief Construct an OldRandomPool + /// \param poolSize internal pool size of the generator + /// \details poolSize must be greater than 16 OldRandomPool(unsigned int poolSize=384); // RandomNumberGenerator interface (Crypto++ 5.5 and above) diff --git a/rc2.h b/rc2.h index 2da4ae49..9a6541ad 100644 --- a/rc2.h +++ b/rc2.h @@ -1,7 +1,7 @@ // rc2.h - originally written and placed in the public domain by Wei Dai -//! \file rc2.h -//! \brief Classes for the RC2 block cipher +/// \file rc2.h +/// \brief Classes for the RC2 block cipher #ifndef CRYPTOPP_RC2_H #define CRYPTOPP_RC2_H @@ -12,8 +12,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RC2_Info -//! \brief RC2 block cipher information +/// \class RC2_Info +/// \brief RC2 block cipher information struct RC2_Info : public FixedBlockSize<8>, public VariableKeyLength<16, 1, 128> { CRYPTOPP_CONSTANT(DEFAULT_EFFECTIVE_KEYLENGTH = 1024) @@ -21,14 +21,14 @@ struct RC2_Info : public FixedBlockSize<8>, public VariableKeyLength<16, 1, 128> CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RC2";} }; -//! \class RC2 -//! \brief RC2 block cipher -//! \sa RC2 on the Crypto Lounge. +/// \class RC2 +/// \brief RC2 block cipher +/// \sa RC2 on the Crypto Lounge. class RC2 : public RC2_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief Class specific methods used to operate the cipher. - //! \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions + /// \class Base + /// \brief Class specific methods used to operate the cipher. + /// \details Implementations and overrides in \p Base apply to both \p ENCRYPTION and \p DECRYPTION directions class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -39,18 +39,18 @@ class RC2 : public RC2_Info, public BlockCipherDocumentation FixedSizeSecBlock K; // expanded key table }; - //! \class Enc - //! \brief Class specific methods used to operate the cipher in the forward direction. - //! \details Implementations and overrides in \p Enc apply to \p ENCRYPTION. + /// \class Enc + /// \brief Class specific methods used to operate the cipher in the forward direction. + /// \details Implementations and overrides in \p Enc apply to \p ENCRYPTION. class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \class Dec - //! \brief Class specific methods used to operate the cipher in the reverse direction. - //! \details Implementations and overrides in \p Dec apply to \p DECRYPTION. + /// \class Dec + /// \brief Class specific methods used to operate the cipher in the reverse direction. + /// \details Implementations and overrides in \p Dec apply to \p DECRYPTION. class CRYPTOPP_NO_VTABLE Dec : public Base { public: @@ -59,9 +59,9 @@ class RC2 : public RC2_Info, public BlockCipherDocumentation public: - //! \class Encryption - //! \brief Class specific methods used to operate the cipher in the forward direction. - //! \details Implementations and overrides in \p Encryption apply to \p ENCRYPTION. + /// \class Encryption + /// \brief Class specific methods used to operate the cipher in the forward direction. + /// \details Implementations and overrides in \p Encryption apply to \p ENCRYPTION. class Encryption : public BlockCipherFinal { public: @@ -72,9 +72,9 @@ public: {SetKey(key, keyLen, MakeParameters("EffectiveKeyLength", effectiveKeyLen));} }; - //! \class Decryption - //! \brief Class specific methods used to operate the cipher in the reverse direction. - //! \details Implementations and overrides in \p Decryption apply to \p DECRYPTION. + /// \class Decryption + /// \brief Class specific methods used to operate the cipher in the reverse direction. + /// \details Implementations and overrides in \p Decryption apply to \p DECRYPTION. class Decryption : public BlockCipherFinal { public: diff --git a/rc5.h b/rc5.h index eb5a5400..0089a3ec 100644 --- a/rc5.h +++ b/rc5.h @@ -1,7 +1,7 @@ // rc5.h - originally written and placed in the public domain by Wei Dai -//! \file rc5.h -//! \brief Classes for the RC5 block cipher +/// \file rc5.h +/// \brief Classes for the RC5 block cipher #ifndef CRYPTOPP_RC5_H #define CRYPTOPP_RC5_H @@ -11,19 +11,19 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RC5_Info -//! \brief RC5 block cipher information -//! \since Crypto++ 1.0 +/// \class RC5_Info +/// \brief RC5 block cipher information +/// \since Crypto++ 1.0 struct RC5_Info : public FixedBlockSize<8>, public VariableKeyLength<16, 0, 255>, public VariableRounds<16> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RC5";} typedef word32 RC5_WORD; }; -//! \class RC5 -//! \brief RC5 block cipher -//! \sa RC5 -//! \since Crypto++ 1.0 +/// \class RC5 +/// \brief RC5 block cipher +/// \sa RC5 +/// \since Crypto++ 1.0 class RC5 : public RC5_Info, public BlockCipherDocumentation { class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl diff --git a/rc6.h b/rc6.h index 45a8f138..4cc0978d 100644 --- a/rc6.h +++ b/rc6.h @@ -1,7 +1,7 @@ // rc6.h - originally written and placed in the public domain by Wei Dai -//! \file rc6.h -//! \brief Classes for the RC6 block cipher +/// \file rc6.h +/// \brief Classes for the RC6 block cipher #ifndef CRYPTOPP_RC6_H #define CRYPTOPP_RC6_H @@ -11,17 +11,17 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RC6_Info -//! \brief RC6 block cipher information +/// \class RC6_Info +/// \brief RC6 block cipher information struct RC6_Info : public FixedBlockSize<16>, public VariableKeyLength<16, 16, 32, 8>, public VariableRounds<20> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RC6";} typedef word32 RC6_WORD; }; -//! \class RC6 -//! \brief RC6 block cipher -//! \sa RC6 +/// \class RC6 +/// \brief RC6 block cipher +/// \sa RC6 class RC6 : public RC6_Info, public BlockCipherDocumentation { class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl diff --git a/rdrand.h b/rdrand.h index 33309017..320d864c 100644 --- a/rdrand.h +++ b/rdrand.h @@ -1,8 +1,8 @@ // rdrand.h - written and placed in public domain by Jeffrey Walton and Uri Blumenthal. -//! \file rdrand.h -//! \brief Classes for RDRAND and RDSEED -//! \since Crypto++ 5.6.3 +/// \file rdrand.h +/// \brief Classes for RDRAND and RDSEED +/// \since Crypto++ 5.6.3 #ifndef CRYPTOPP_RDRAND_H #define CRYPTOPP_RDRAND_H @@ -32,9 +32,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Exception thrown when a RDRAND generator encounters -//! a generator related error. -//! \since Crypto++ 5.6.3 +/// \brief Exception thrown when a RDRAND generator encounters +/// a generator related error. +/// \since Crypto++ 5.6.3 class RDRAND_Err : public Exception { public: @@ -42,9 +42,9 @@ public: : Exception(OTHER_ERROR, "RDRAND: " + operation + " operation failed") {} }; -//! \brief Hardware generated random numbers using RDRAND instruction -//! \sa MaurerRandomnessTest() for random bit generators -//! \since Crypto++ 5.6.3 +/// \brief Hardware generated random numbers using RDRAND instruction +/// \sa MaurerRandomnessTest() for random bit generators +/// \since Crypto++ 5.6.3 class RDRAND : public RandomNumberGenerator { public: @@ -52,29 +52,29 @@ public: virtual ~RDRAND() {} - //! \brief Construct a RDRAND generator - //! \details According to DJ of Intel, the Intel RDRAND circuit does not underflow. - //! If it did hypothetically underflow, then it would return 0 for the random value. - //! AMD's RDRAND implementation appears to provide the same behavior. - //! \throws RDRAND_Err if the random number generator is not available + /// \brief Construct a RDRAND generator + /// \details According to DJ of Intel, the Intel RDRAND circuit does not underflow. + /// If it did hypothetically underflow, then it would return 0 for the random value. + /// AMD's RDRAND implementation appears to provide the same behavior. + /// \throws RDRAND_Err if the random number generator is not available RDRAND(); - //! \brief Generate random array of bytes - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes + /// \brief Generate random array of bytes + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes virtual void GenerateBlock(byte *output, size_t size); - //! \brief Generate and discard n bytes - //! \param n the number of bytes to generate and discard - //! \details the RDSEED generator discards words, not bytes. If n is - //! not a multiple of a machine word, then it is rounded up to - //! that size. + /// \brief Generate and discard n bytes + /// \param n the number of bytes to generate and discard + /// \details the RDSEED generator discards words, not bytes. If n is + /// not a multiple of a machine word, then it is rounded up to + /// that size. virtual void DiscardBytes(size_t n); - //! \brief Update RNG state with additional unpredictable values - //! \param input unused - //! \param length unused - //! \details The operation is a nop for this generator. + /// \brief Update RNG state with additional unpredictable values + /// \param input unused + /// \param length unused + /// \details The operation is a nop for this generator. virtual void IncorporateEntropy(const byte *input, size_t length) { // Override to avoid the base class' throw. @@ -82,9 +82,9 @@ public: } }; -//! \brief Exception thrown when a RDSEED generator encounters -//! a generator related error. -//! \since Crypto++ 5.6.3 +/// \brief Exception thrown when a RDSEED generator encounters +/// a generator related error. +/// \since Crypto++ 5.6.3 class RDSEED_Err : public Exception { public: @@ -92,9 +92,9 @@ public: : Exception(OTHER_ERROR, "RDSEED: " + operation + " operation failed") {} }; -//! \brief Hardware generated random numbers using RDSEED instruction -//! \sa MaurerRandomnessTest() for random bit generators -//! \since Crypto++ 5.6.3 +/// \brief Hardware generated random numbers using RDSEED instruction +/// \sa MaurerRandomnessTest() for random bit generators +/// \since Crypto++ 5.6.3 class RDSEED : public RandomNumberGenerator { public: @@ -102,29 +102,29 @@ public: virtual ~RDSEED() {} - //! \brief Construct a RDSEED generator - //! \details Empirical testing under a 6th generaton i7 (6200U) shows RDSEED fails - //! to fulfill requests at about once every for every 256 bytes requested. - //! The generator runs about 4 times slower than RDRAND. - //! \throws RDSEED_Err if the random number generator is not available + /// \brief Construct a RDSEED generator + /// \details Empirical testing under a 6th generaton i7 (6200U) shows RDSEED fails + /// to fulfill requests at about once every for every 256 bytes requested. + /// The generator runs about 4 times slower than RDRAND. + /// \throws RDSEED_Err if the random number generator is not available RDSEED(); - //! \brief Generate random array of bytes - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes + /// \brief Generate random array of bytes + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes virtual void GenerateBlock(byte *output, size_t size); - //! \brief Generate and discard n bytes - //! \param n the number of bytes to generate and discard - //! \details the RDSEED generator discards words, not bytes. If n is - //! not a multiple of a machine word, then it is rounded up to - //! that size. + /// \brief Generate and discard n bytes + /// \param n the number of bytes to generate and discard + /// \details the RDSEED generator discards words, not bytes. If n is + /// not a multiple of a machine word, then it is rounded up to + /// that size. virtual void DiscardBytes(size_t n); - //! \brief Update RNG state with additional unpredictable values - //! \param input unused - //! \param length unused - //! \details The operation is a nop for this generator. + /// \brief Update RNG state with additional unpredictable values + /// \param input unused + /// \param length unused + /// \details The operation is a nop for this generator. virtual void IncorporateEntropy(const byte *input, size_t length) { // Override to avoid the base class' throw. diff --git a/rijndael.h b/rijndael.h index 61e3c5f3..413d2ebf 100644 --- a/rijndael.h +++ b/rijndael.h @@ -1,11 +1,11 @@ // rijndael.h - originally written and placed in the public domain by Wei Dai -//! \file rijndael.h -//! \brief Classes for Rijndael encryption algorithm -//! \details All key sizes are supported. The library only provides Rijndael with 128-bit blocks, -//! and not 192-bit or 256-bit blocks -//! \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, -//! Power8 AES since Crypto++ 6.0 +/// \file rijndael.h +/// \brief Classes for Rijndael encryption algorithm +/// \details All key sizes are supported. The library only provides Rijndael with 128-bit blocks, +/// and not 192-bit or 256-bit blocks +/// \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, +/// Power8 AES since Crypto++ 6.0 #ifndef CRYPTOPP_RIJNDAEL_H #define CRYPTOPP_RIJNDAEL_H @@ -20,26 +20,26 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Rijndael block cipher information -//! \details All key sizes are supported. The library only provides Rijndael with 128-bit blocks, -//! and not 192-bit or 256-bit blocks -//! \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, -//! Power8 AES since Crypto++ 6.0 +/// \brief Rijndael block cipher information +/// \details All key sizes are supported. The library only provides Rijndael with 128-bit blocks, +/// and not 192-bit or 256-bit blocks +/// \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, +/// Power8 AES since Crypto++ 6.0 struct Rijndael_Info : public FixedBlockSize<16>, public VariableKeyLength<16, 16, 32, 8> { CRYPTOPP_DLL static const char * CRYPTOPP_API StaticAlgorithmName() {return CRYPTOPP_RIJNDAEL_NAME;} }; -//! \brief Rijndael block cipher -//! \details All key sizes are supported. The library only provides Rijndael with 128-bit blocks, -//! and not 192-bit or 256-bit blocks -//! \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, -//! Power8 AES since Crypto++ 6.0 -//! \sa Rijndael +/// \brief Rijndael block cipher +/// \details All key sizes are supported. The library only provides Rijndael with 128-bit blocks, +/// and not 192-bit or 256-bit blocks +/// \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, +/// Power8 AES since Crypto++ 6.0 +/// \sa Rijndael class CRYPTOPP_DLL Rijndael : public Rijndael_Info, public BlockCipherDocumentation { - //! \brief Rijndael block cipher transformation functions - //! \details Provides implementation common to encryption and decryption + /// \brief Rijndael block cipher transformation functions + /// \details Provides implementation common to encryption and decryption class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -60,11 +60,11 @@ class CRYPTOPP_DLL Rijndael : public Rijndael_Info, public BlockCipherDocumentat mutable SecByteBlock m_aliasBlock; }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key sizes are supported. - //! The library only provides Rijndael with 128-bit blocks, and not 192-bit or 256-bit blocks - //! \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, - //! Power8 AES since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key sizes are supported. + /// The library only provides Rijndael with 128-bit blocks, and not 192-bit or 256-bit blocks + /// \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, + /// Power8 AES since Crypto++ 6.0 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Enc : public Base { public: @@ -74,11 +74,11 @@ class CRYPTOPP_DLL Rijndael : public Rijndael_Info, public BlockCipherDocumentat #endif }; - //! \brief Provides implementation for decryption transformation - //! \details Dec provides implementation for decryption transformation. All key sizes are supported. - //! The library only provides Rijndael with 128-bit blocks, and not 192-bit or 256-bit blocks - //! \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, - //! Power8 AES since Crypto++ 6.0 + /// \brief Provides implementation for decryption transformation + /// \details Dec provides implementation for decryption transformation. All key sizes are supported. + /// The library only provides Rijndael with 128-bit blocks, and not 192-bit or 256-bit blocks + /// \since Rijndael since Crypto++ 3.2, Intel AESNI since Crypto++ 5.6.1, ARMv8 AES since Crypto++ 6.0, + /// Power8 AES since Crypto++ 6.0 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Dec : public Base { public: diff --git a/ripemd.h b/ripemd.h index a73e3409..1ffc5423 100644 --- a/ripemd.h +++ b/ripemd.h @@ -1,7 +1,7 @@ // ripemd.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \brief Classes for RIPEMD message digest +/// \file +/// \brief Classes for RIPEMD message digest #ifndef CRYPTOPP_RIPEMD_H #define CRYPTOPP_RIPEMD_H @@ -10,10 +10,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RIPEMD160 -//! \brief RIPEMD-160 message digest -//! \details Digest size is 160-bits. -//! \sa RIPEMD-160 +/// \class RIPEMD160 +/// \brief RIPEMD-160 message digest +/// \details Digest size is 160-bits. +/// \sa RIPEMD-160 class RIPEMD160 : public IteratedHashWithStaticTransform { public: @@ -22,10 +22,10 @@ public: CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RIPEMD-160";} }; -//! \class RIPEMD320 -//! \brief RIPEMD-320 message digest -//! \details Digest size is 320-bits. -//! \sa RIPEMD-320 +/// \class RIPEMD320 +/// \brief RIPEMD-320 message digest +/// \details Digest size is 320-bits. +/// \sa RIPEMD-320 class RIPEMD320 : public IteratedHashWithStaticTransform { public: @@ -34,11 +34,11 @@ public: CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RIPEMD-320";} }; -//! \class RIPEMD128 -//! \brief RIPEMD-128 message digest -//! \details Digest size is 128-bits. -//! \warning RIPEMD-128 is considered insecure, and should not be used unless you absolutely need it for compatibility. -//! \sa RIPEMD-128 +/// \class RIPEMD128 +/// \brief RIPEMD-128 message digest +/// \details Digest size is 128-bits. +/// \warning RIPEMD-128 is considered insecure, and should not be used unless you absolutely need it for compatibility. +/// \sa RIPEMD-128 class RIPEMD128 : public IteratedHashWithStaticTransform { public: @@ -47,11 +47,11 @@ public: CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RIPEMD-128";} }; -//! \class RIPEMD256 -//! \brief RIPEMD-256 message digest -//! \details Digest size is 256-bits. -//! \warning RIPEMD-256 is considered insecure, and should not be used unless you absolutely need it for compatibility. -//! \sa RIPEMD-256 +/// \class RIPEMD256 +/// \brief RIPEMD-256 message digest +/// \details Digest size is 256-bits. +/// \warning RIPEMD-256 is considered insecure, and should not be used unless you absolutely need it for compatibility. +/// \sa RIPEMD-256 class RIPEMD256 : public IteratedHashWithStaticTransform { public: diff --git a/rng.h b/rng.h index dc18cb48..bde20947 100644 --- a/rng.h +++ b/rng.h @@ -1,10 +1,10 @@ // rng.h - originally written and placed in the public domain by Wei Dai -//! \file rng.h -//! \brief Miscellaneous classes for RNGs -//! \details This file contains miscellaneous classes for RNGs, including LC_RNG(), -//! X917RNG() and MaurerRandomnessTest() -//! \sa osrng.h, randpool.h +/// \file rng.h +/// \brief Miscellaneous classes for RNGs +/// \details This file contains miscellaneous classes for RNGs, including LC_RNG(), +/// X917RNG() and MaurerRandomnessTest() +/// \sa osrng.h, randpool.h #ifndef CRYPTOPP_RNG_H #define CRYPTOPP_RNG_H @@ -15,15 +15,15 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Linear Congruential Generator (LCG) -//! \details Originally propsed by William S. England. -//! \warning LC_RNG is suitable for simulations, where uniformaly distrubuted numbers are -//! required quickly. It should not be used for cryptographic purposes. +/// \brief Linear Congruential Generator (LCG) +/// \details Originally propsed by William S. England. +/// \warning LC_RNG is suitable for simulations, where uniformaly distrubuted numbers are +/// required quickly. It should not be used for cryptographic purposes. class LC_RNG : public RandomNumberGenerator { public: - //! \brief Construct a Linear Congruential Generator (LCG) - //! \param init_seed the initial value for the generator + /// \brief Construct a Linear Congruential Generator (LCG) + /// \param init_seed the initial value for the generator LC_RNG(word32 init_seed) : seed(init_seed) {} @@ -40,30 +40,30 @@ private: static const word16 r; }; -//! \class X917RNG -//! \brief ANSI X9.17 RNG -//! \details X917RNG is from ANSI X9.17 Appendix C, and it uses a 64-bit block cipher, like TripleDES. -//! If you use a 128-bit block cipher, like AES, then you are effectively using an ANSI X9.31 generator. -//! \sa AutoSeededX917RNG, DefaultAutoSeededRNG +/// \class X917RNG +/// \brief ANSI X9.17 RNG +/// \details X917RNG is from ANSI X9.17 Appendix C, and it uses a 64-bit block cipher, like TripleDES. +/// If you use a 128-bit block cipher, like AES, then you are effectively using an ANSI X9.31 generator. +/// \sa AutoSeededX917RNG, DefaultAutoSeededRNG class CRYPTOPP_DLL X917RNG : public RandomNumberGenerator, public NotCopyable { public: - //! \brief Construct a X917RNG - //! \param cipher the block cipher to use for the generator - //! \param seed a byte buffer to use as a seed - //! \param deterministicTimeVector additional entropy - //! \details cipher will be deleted by the destructor. seed must be at least - //! BlockSize() in length. deterministicTimeVector = 0 means obtain time vector - //! from the system. - //! \details When constructing a X917RNG, the generator must be keyed or an access - //! violation will occur because the time vector is encrypted using the block cipher. - //! To key the generator during constructions, perform the following: - //! 
-	//!   SecByteBlock key(AES::DEFAULT_KEYLENGTH), seed(AES::BLOCKSIZE);
-	//!   OS_GenerateRandomBlock(false, key, key.size());
-	//!   OS_GenerateRandomBlock(false, seed, seed.size());
-	//!   X917RNG prng(new AES::Encryption(key, AES::DEFAULT_KEYLENGTH), seed, NULLPTR);
- //! \sa AutoSeededX917RNG + /// \brief Construct a X917RNG + /// \param cipher the block cipher to use for the generator + /// \param seed a byte buffer to use as a seed + /// \param deterministicTimeVector additional entropy + /// \details cipher will be deleted by the destructor. seed must be at least + /// BlockSize() in length. deterministicTimeVector = 0 means obtain time vector + /// from the system. + /// \details When constructing a X917RNG, the generator must be keyed or an access + /// violation will occur because the time vector is encrypted using the block cipher. + /// To key the generator during constructions, perform the following: + /// 
+	///   SecByteBlock key(AES::DEFAULT_KEYLENGTH), seed(AES::BLOCKSIZE);
+	///   OS_GenerateRandomBlock(false, key, key.size());
+	///   OS_GenerateRandomBlock(false, seed, seed.size());
+	///   X917RNG prng(new AES::Encryption(key, AES::DEFAULT_KEYLENGTH), seed, NULLPTR);
+ /// \sa AutoSeededX917RNG X917RNG(BlockTransformation *cipher, const byte *seed, const byte *deterministicTimeVector = NULLPTR); void GenerateIntoBufferedTransformation(BufferedTransformation &target, const std::string &channel, lword size); @@ -75,22 +75,22 @@ private: SecByteBlock m_randseed, m_lastBlock, m_deterministicTimeVector; }; -//! \class MaurerRandomnessTest -//! \brief Maurer's Universal Statistical Test for Random Bit Generators -//! \details This class implements Maurer's Universal Statistical Test for -//! Random Bit Generators. It is intended for measuring the randomness of -//! *PHYSICAL* RNGs. -//! \details For more details see Maurer's paper in Journal of Cryptology, 1992. +/// \class MaurerRandomnessTest +/// \brief Maurer's Universal Statistical Test for Random Bit Generators +/// \details This class implements Maurer's Universal Statistical Test for +/// Random Bit Generators. It is intended for measuring the randomness of +/// *PHYSICAL* RNGs. +/// \details For more details see Maurer's paper in Journal of Cryptology, 1992. class MaurerRandomnessTest : public Bufferless { public: - //! \brief Construct a MaurerRandomnessTest + /// \brief Construct a MaurerRandomnessTest MaurerRandomnessTest(); size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking); - //! \brief Provides the number of bytes of input is needed by the test - //! \returns how many more bytes of input is needed by the test + /// \brief Provides the number of bytes of input is needed by the test + /// \returns how many more bytes of input is needed by the test // BytesNeeded() returns how many more bytes of input is needed by the test // GetTestValue() should not be called before BytesNeeded()==0 unsigned int BytesNeeded() const {return n >= (Q+K) ? 0 : Q+K-n;} diff --git a/rsa.h b/rsa.h index f4c8fe20..63ef6303 100644 --- a/rsa.h +++ b/rsa.h @@ -1,9 +1,9 @@ // rsa.h - originally written and placed in the public domain by Wei Dai -//! \file rsa.h -//! \brief Classes for the RSA cryptosystem -//! \details This file contains classes that implement the RSA -//! ciphers and signature schemes as defined in PKCS #1 v2.0. +/// \file rsa.h +/// \brief Classes for the RSA cryptosystem +/// \details This file contains classes that implement the RSA +/// ciphers and signature schemes as defined in PKCS #1 v2.0. #ifndef CRYPTOPP_RSA_H #define CRYPTOPP_RSA_H @@ -18,17 +18,17 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RSAFunction -//! \brief RSA trapdoor function using the public key -//! \since Crypto++ 1.0 +/// \class RSAFunction +/// \brief RSA trapdoor function using the public key +/// \since Crypto++ 1.0 class CRYPTOPP_DLL RSAFunction : public TrapdoorFunction, public X509PublicKey { typedef RSAFunction ThisClass; public: - //! \brief Initialize a RSA public key - //! \param n the modulus - //! \param e the public exponent + /// \brief Initialize a RSA public key + /// \param n the modulus + /// \param e the public exponent void Initialize(const Integer &n, const Integer &e) {m_n = n; m_e = e;} @@ -58,43 +58,43 @@ protected: Integer m_n, m_e; }; -//! \class InvertibleRSAFunction -//! \brief RSA trapdoor function using the private key -//! \since Crypto++ 1.0 +/// \class InvertibleRSAFunction +/// \brief RSA trapdoor function using the private key +/// \since Crypto++ 1.0 class CRYPTOPP_DLL InvertibleRSAFunction : public RSAFunction, public TrapdoorFunctionInverse, public PKCS8PrivateKey { typedef InvertibleRSAFunction ThisClass; public: - //! \brief Create a RSA private key - //! \param rng a RandomNumberGenerator derived class - //! \param modulusBits the size of the modulus, in bits - //! \param e the desired public exponent - //! \details Initialize() creates a new keypair using a public exponent of 17. - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a RSA private key + /// \param rng a RandomNumberGenerator derived class + /// \param modulusBits the size of the modulus, in bits + /// \param e the desired public exponent + /// \details Initialize() creates a new keypair using a public exponent of 17. + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits, const Integer &e = 17); - //! \brief Initialize a RSA private key - //! \param n modulus - //! \param e public exponent - //! \param d private exponent - //! \param p first prime factor - //! \param q second prime factor - //! \param dp d mod p - //! \param dq d mod q - //! \param u q-1 mod p - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize a RSA private key + /// \param n modulus + /// \param e public exponent + /// \param d private exponent + /// \param p first prime factor + /// \param q second prime factor + /// \param dp d mod p + /// \param dq d mod q + /// \param u q-1 mod p + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const Integer &n, const Integer &e, const Integer &d, const Integer &p, const Integer &q, const Integer &dp, const Integer &dq, const Integer &u) {m_n = n; m_e = e; m_d = d; m_p = p; m_q = q; m_dp = dp; m_dq = dq; m_u = u;} - //! \brief Initialize a RSA private key - //! \param n modulus - //! \param e public exponent - //! \param d private exponent - //! \details This Initialize() function overload initializes a private key from existing parameters. - //! Initialize() will factor n using d and populate {p,q,dp,dq,u}. + /// \brief Initialize a RSA private key + /// \param n modulus + /// \param e public exponent + /// \param d private exponent + /// \details This Initialize() function overload initializes a private key from existing parameters. + /// Initialize() will factor n using d and populate {p,q,dp,dq,u}. void Initialize(const Integer &n, const Integer &e, const Integer &d); // PKCS8PrivateKey @@ -139,9 +139,9 @@ protected: Integer m_d, m_p, m_q, m_dp, m_dq, m_u; }; -//! \class RSAFunction_ISO -//! \brief RSA trapdoor function using the public key -//! \since Crypto++ 1.0 +/// \class RSAFunction_ISO +/// \brief RSA trapdoor function using the public key +/// \since Crypto++ 1.0 class CRYPTOPP_DLL RSAFunction_ISO : public RSAFunction { public: @@ -149,9 +149,9 @@ public: Integer PreimageBound() const {return ++(m_n>>1);} }; -//! \class InvertibleRSAFunction_ISO -//! \brief RSA trapdoor function using the private key -//! \since Crypto++ 1.0 +/// \class InvertibleRSAFunction_ISO +/// \brief RSA trapdoor function using the private key +/// \since Crypto++ 1.0 class CRYPTOPP_DLL InvertibleRSAFunction_ISO : public InvertibleRSAFunction { public: @@ -159,9 +159,9 @@ public: Integer PreimageBound() const {return ++(m_n>>1);} }; -//! \class RSA -//! \brief RSA algorithm -//! \since Crypto++ 1.0 +/// \class RSA +/// \brief RSA algorithm +/// \since Crypto++ 1.0 struct CRYPTOPP_DLL RSA { CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "RSA";} @@ -169,31 +169,31 @@ struct CRYPTOPP_DLL RSA typedef InvertibleRSAFunction PrivateKey; }; -//! \class RSAES -//! \brief RSA encryption algorithm -//! \tparam STANDARD signature standard -//! \sa RSA cryptosystem -//! \since Crypto++ 1.0 +/// \class RSAES +/// \brief RSA encryption algorithm +/// \tparam STANDARD signature standard +/// \sa RSA cryptosystem +/// \since Crypto++ 1.0 template struct RSAES : public TF_ES { }; -//! \class RSASS -//! \brief RSA signature algorithm -//! \tparam STANDARD signature standard -//! \tparam H hash transformation -//! \details See documentation of PKCS1v15 for a list of hash functions that can be used with it. -//! \sa RSA signature scheme with appendix -//! \since Crypto++ 1.0 +/// \class RSASS +/// \brief RSA signature algorithm +/// \tparam STANDARD signature standard +/// \tparam H hash transformation +/// \details See documentation of PKCS1v15 for a list of hash functions that can be used with it. +/// \sa RSA signature scheme with appendix +/// \since Crypto++ 1.0 template struct RSASS : public TF_SS { }; -//! \class RSA_ISO -//! \brief RSA algorithm -//! \since Crypto++ 1.0 +/// \class RSA_ISO +/// \brief RSA algorithm +/// \since Crypto++ 1.0 struct CRYPTOPP_DLL RSA_ISO { CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "RSA-ISO";} @@ -201,57 +201,57 @@ struct CRYPTOPP_DLL RSA_ISO typedef InvertibleRSAFunction_ISO PrivateKey; }; -//! \class RSASS_ISO -//! \brief RSA signature algorithm -//! \tparam H hash transformation -//! \since Crypto++ 1.0 +/// \class RSASS_ISO +/// \brief RSA signature algorithm +/// \tparam H hash transformation +/// \since Crypto++ 1.0 template struct RSASS_ISO : public TF_SS { }; -//! \brief \ref RSAES "RSAES::Decryptor" typedef -//! \details RSA encryption scheme defined in PKCS #1 v2.0 +/// \brief \ref RSAES "RSAES::Decryptor" typedef +/// \details RSA encryption scheme defined in PKCS #1 v2.0 DOCUMENTED_TYPEDEF(RSAES::Decryptor, RSAES_PKCS1v15_Decryptor); -//! \brief \ref RSAES "RSAES::Encryptor" typedef -//! \details RSA encryption scheme defined in PKCS #1 v2.0 +/// \brief \ref RSAES "RSAES::Encryptor" typedef +/// \details RSA encryption scheme defined in PKCS #1 v2.0 DOCUMENTED_TYPEDEF(RSAES::Encryptor, RSAES_PKCS1v15_Encryptor); -//! \brief \ref RSAES "RSAES>::Decryptor" typedef -//! \details RSA encryption scheme defined in PKCS #1 v2.0 +/// \brief \ref RSAES "RSAES>::Decryptor" typedef +/// \details RSA encryption scheme defined in PKCS #1 v2.0 DOCUMENTED_TYPEDEF(RSAES >::Decryptor, RSAES_OAEP_SHA_Decryptor); -//! \brief \ref RSAES "RSAES>::Encryptor" typedef -//! \details RSA encryption scheme defined in PKCS #1 v2.0 +/// \brief \ref RSAES "RSAES>::Encryptor" typedef +/// \details RSA encryption scheme defined in PKCS #1 v2.0 DOCUMENTED_TYPEDEF(RSAES >::Encryptor, RSAES_OAEP_SHA_Encryptor); #ifdef CRYPTOPP_DOXYGEN_PROCESSING -//! \brief \ref RSASS "RSASS::Signer" typedef -//! \details RSA signature schemes defined in PKCS #1 v2.0 -//! \since Crypto++ 1.0 +/// \brief \ref RSASS "RSASS::Signer" typedef +/// \details RSA signature schemes defined in PKCS #1 v2.0 +/// \since Crypto++ 1.0 class RSASSA_PKCS1v15_SHA_Signer : public RSASS::Signer {}; -//! \brief \ref RSASS "RSASS::Verifier" typedef -//! \details RSA signature schemes defined in PKCS #1 v2.0 -//! \since Crypto++ 1.0 +/// \brief \ref RSASS "RSASS::Verifier" typedef +/// \details RSA signature schemes defined in PKCS #1 v2.0 +/// \since Crypto++ 1.0 class RSASSA_PKCS1v15_SHA_Verifier : public RSASS::Verifier {}; namespace Weak { -//! \brief \ref RSASS "RSASS::Signer" typedef -//! \details RSA signature schemes defined in PKCS #1 v2.0 -//! \since Crypto++ 1.0 +/// \brief \ref RSASS "RSASS::Signer" typedef +/// \details RSA signature schemes defined in PKCS #1 v2.0 +/// \since Crypto++ 1.0 class RSASSA_PKCS1v15_MD2_Signer : public RSASS::Signer {}; -//! \brief \ref RSASS "RSASS::Verifier" typedef -//! \details RSA signature schemes defined in PKCS #1 v2.0 -//! \since Crypto++ 1.0 +/// \brief \ref RSASS "RSASS::Verifier" typedef +/// \details RSA signature schemes defined in PKCS #1 v2.0 +/// \since Crypto++ 1.0 class RSASSA_PKCS1v15_MD2_Verifier : public RSASS::Verifier {}; -//! \brief \ref RSASS "RSASS::Signer" typedef -//! \details RSA signature schemes defined in PKCS #1 v2.0 -//! \since Crypto++ 1.0 +/// \brief \ref RSASS "RSASS::Signer" typedef +/// \details RSA signature schemes defined in PKCS #1 v2.0 +/// \since Crypto++ 1.0 class RSASSA_PKCS1v15_MD5_Signer : public RSASS::Signer {}; -//! \brief \ref RSASS "RSASS::Verifier" typedef -//! \details RSA signature schemes defined in PKCS #1 v2.0 -//! \since Crypto++ 1.0 +/// \brief \ref RSASS "RSASS::Verifier" typedef +/// \details RSA signature schemes defined in PKCS #1 v2.0 +/// \since Crypto++ 1.0 class RSASSA_PKCS1v15_MD5_Verifier : public RSASS::Verifier {}; } diff --git a/rw.h b/rw.h index 5fcfddf4..f6274c9d 100644 --- a/rw.h +++ b/rw.h @@ -1,12 +1,12 @@ // rw.h - originally written and placed in the public domain by Wei Dai -//! \file rw.h -//! \brief Classes for Rabin-Williams signature scheme -//! \details The implementation provides Rabin-Williams signature schemes as defined in -//! IEEE P1363. It uses Bernstein's tweaked square roots in place of square roots to -//! speedup calculations. -//! \sa RSA signatures and Rabin–Williams -//! signatures: the state of the art (20080131), Section 6, The tweaks e and f. +/// \file rw.h +/// \brief Classes for Rabin-Williams signature scheme +/// \details The implementation provides Rabin-Williams signature schemes as defined in +/// IEEE P1363. It uses Bernstein's tweaked square roots in place of square roots to +/// speedup calculations. +/// \sa RSA signatures and Rabin–Williams +/// signatures: the state of the art (20080131), Section 6, The tweaks e and f. #ifndef CRYPTOPP_RW_H #define CRYPTOPP_RW_H @@ -17,17 +17,17 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class RWFunction -//! \brief Rabin-Williams trapdoor function using the public key -//! \since Crypto++ 2.0, Tweaked roots using e and f since Crypto++ 5.6.4 +/// \class RWFunction +/// \brief Rabin-Williams trapdoor function using the public key +/// \since Crypto++ 2.0, Tweaked roots using e and f since Crypto++ 5.6.4 class CRYPTOPP_DLL RWFunction : public TrapdoorFunction, public PublicKey { typedef RWFunction ThisClass; public: - //! \brief Initialize a Rabin-Williams public key - //! \param n the modulus + /// \brief Initialize a Rabin-Williams public key + /// \param n the modulus void Initialize(const Integer &n) {m_n = n;} @@ -54,31 +54,31 @@ protected: Integer m_n; }; -//! \class InvertibleRWFunction -//! \brief Rabin-Williams trapdoor function using the private key -//! \since Crypto++ 2.0, Tweaked roots using e and f since Crypto++ 5.6.4 +/// \class InvertibleRWFunction +/// \brief Rabin-Williams trapdoor function using the private key +/// \since Crypto++ 2.0, Tweaked roots using e and f since Crypto++ 5.6.4 class CRYPTOPP_DLL InvertibleRWFunction : public RWFunction, public TrapdoorFunctionInverse, public PrivateKey { typedef InvertibleRWFunction ThisClass; public: - //! \brief Construct an InvertibleRWFunction + /// \brief Construct an InvertibleRWFunction InvertibleRWFunction() : m_precompute(false) {} - //! \brief Initialize a Rabin-Williams private key - //! \param n modulus - //! \param p first prime factor - //! \param q second prime factor - //! \param u q-1 mod p - //! \details This Initialize() function overload initializes a private key from existing parameters. + /// \brief Initialize a Rabin-Williams private key + /// \param n modulus + /// \param p first prime factor + /// \param q second prime factor + /// \param u q-1 mod p + /// \details This Initialize() function overload initializes a private key from existing parameters. void Initialize(const Integer &n, const Integer &p, const Integer &q, const Integer &u); - //! \brief Create a Rabin-Williams private key - //! \param rng a RandomNumberGenerator derived class - //! \param modulusBits the size of the modulus, in bits - //! \details This function overload of Initialize() creates a new private key because it - //! takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, - //! then use one of the other Initialize() overloads. + /// \brief Create a Rabin-Williams private key + /// \param rng a RandomNumberGenerator derived class + /// \param modulusBits the size of the modulus, in bits + /// \details This function overload of Initialize() creates a new private key because it + /// takes a RandomNumberGenerator() as a parameter. If you have an existing keypair, + /// then use one of the other Initialize() overloads. void Initialize(RandomNumberGenerator &rng, unsigned int modulusBits) {GenerateRandomWithKeySize(rng, modulusBits);} @@ -124,7 +124,7 @@ protected: mutable bool m_precompute; }; -//! \brief Rabin-Williams keys +/// \brief Rabin-Williams keys struct RW { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "RW";} @@ -132,9 +132,9 @@ struct RW typedef InvertibleRWFunction PrivateKey; }; -//! \brief Rabin-Williams signature scheme -//! \tparam STANDARD signature standard -//! \tparam H hash transformation +/// \brief Rabin-Williams signature scheme +/// \tparam STANDARD signature standard +/// \tparam H hash transformation template struct RWSS : public TF_SS { diff --git a/safer.h b/safer.h index 67b606eb..78d3e1e3 100644 --- a/safer.h +++ b/safer.h @@ -1,7 +1,7 @@ // safer.h - originally written and placed in the public domain by Wei Dai -//! \file safer.h -//! \brief Classes for the SAFER and SAFER-K block ciphers +/// \file safer.h +/// \brief Classes for the SAFER and SAFER-K block ciphers #ifndef CRYPTOPP_SAFER_H #define CRYPTOPP_SAFER_H @@ -11,13 +11,13 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SAFER -//! \brief SAFER block cipher +/// \class SAFER +/// \brief SAFER block cipher class SAFER { public: - //! \class Base - //! \brief SAFER block cipher default operation + /// \class Base + /// \brief SAFER block cipher default operation class CRYPTOPP_NO_VTABLE Base : public BlockCipher { public: @@ -32,16 +32,16 @@ public: static const byte log_tab[256]; }; - //! \class Enc - //! \brief SAFER block cipher encryption operation + /// \class Enc + /// \brief SAFER block cipher encryption operation class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \class Dec - //! \brief SAFER block cipher decryption operation + /// \class Dec + /// \brief SAFER block cipher decryption operation class CRYPTOPP_NO_VTABLE Dec : public Base { public: @@ -49,12 +49,12 @@ public: }; }; -//! \class SAFER_Impl -//! \brief SAFER block cipher default implementation -//! \tparam BASE SAFER::Enc or SAFER::Dec derived base class -//! \tparam INFO SAFER_Info derived class -//! \tparam STR flag indicating a strengthened implementation -//! \details SAFER-K is not strengthened; while SAFER-SK is strengthened. +/// \class SAFER_Impl +/// \brief SAFER block cipher default implementation +/// \tparam BASE SAFER::Enc or SAFER::Dec derived base class +/// \tparam INFO SAFER_Info derived class +/// \tparam STR flag indicating a strengthened implementation +/// \details SAFER-K is not strengthened; while SAFER-SK is strengthened. template class CRYPTOPP_NO_VTABLE SAFER_Impl : public BlockCipherImpl { @@ -62,16 +62,16 @@ protected: bool Strengthened() const {return STR;} }; -//! \class SAFER_K_Info -//! \brief SAFER-K block cipher information +/// \class SAFER_K_Info +/// \brief SAFER-K block cipher information struct SAFER_K_Info : public FixedBlockSize<8>, public VariableKeyLength<16, 8, 16, 8>, public VariableRounds<10, 1, 13> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "SAFER-K";} }; -//! \class SAFER_K -//! \brief SAFER-K block cipher -//! \sa SAFER-K +/// \class SAFER_K +/// \brief SAFER-K block cipher +/// \sa SAFER-K class SAFER_K : public SAFER_K_Info, public SAFER, public BlockCipherDocumentation { public: @@ -79,16 +79,16 @@ public: typedef BlockCipherFinal > Decryption; }; -//! \class SAFER_SK_Info -//! \brief SAFER-SK block cipher information +/// \class SAFER_SK_Info +/// \brief SAFER-SK block cipher information struct SAFER_SK_Info : public FixedBlockSize<8>, public VariableKeyLength<16, 8, 16, 8>, public VariableRounds<10, 1, 13> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "SAFER-SK";} }; -//! \class SAFER_SK -//! \brief SAFER-SK block cipher -//! \sa SAFER-SK +/// \class SAFER_SK +/// \brief SAFER-SK block cipher +/// \sa SAFER-SK class SAFER_SK : public SAFER_SK_Info, public SAFER, public BlockCipherDocumentation { public: diff --git a/salsa.cpp b/salsa.cpp index 3b764b11..5fc3a91a 100644 --- a/salsa.cpp +++ b/salsa.cpp @@ -16,8 +16,6 @@ # pragma warning(disable: 4702 4740) #endif -// TODO: work around GCC 4.8+ issue with SSE2 ASM until the exact details are known -// and fix is released. Duplicate with "valgrind ./cryptest.exe tv salsa" // Clang due to "Inline assembly operands don't work with .intel_syntax" // https://llvm.org/bugs/show_bug.cgi?id=24232 #if defined(CRYPTOPP_DISABLE_SALSA_ASM) diff --git a/salsa.h b/salsa.h index b7b6aa06..db3c469a 100644 --- a/salsa.h +++ b/salsa.h @@ -1,7 +1,7 @@ // salsa.h - originally written and placed in the public domain by Wei Dai -//! \file salsa.h -//! \brief Classes for Salsa and Salsa20 stream ciphers +/// \file salsa.h +/// \brief Classes for Salsa and Salsa20 stream ciphers #ifndef CRYPTOPP_SALSA_H #define CRYPTOPP_SALSA_H @@ -16,15 +16,15 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Salsa20_Info -//! \brief Salsa20 stream cipher information +/// \class Salsa20_Info +/// \brief Salsa20 stream cipher information struct Salsa20_Info : public VariableKeyLength<32, 16, 32, 16, SimpleKeyingInterface::UNIQUE_IV, 8> { static std::string StaticAlgorithmName() {return "Salsa20";} }; -//! \class Salsa20_Policy -//! \brief Salsa20 stream cipher operation +/// \class Salsa20_Policy +/// \brief Salsa20 stream cipher operation class CRYPTOPP_NO_VTABLE Salsa20_Policy : public AdditiveCipherConcretePolicy { protected: @@ -42,25 +42,25 @@ protected: int m_rounds; }; -//! \class Salsa20 -//! \brief Salsa20 stream cipher -//! \details Salsa20 provides a variable number of rounds: 8, 12 or 20. The default number of rounds is 20. -//! \sa XSalsa20 +/// \class Salsa20 +/// \brief Salsa20 stream cipher +/// \details Salsa20 provides a variable number of rounds: 8, 12 or 20. The default number of rounds is 20. +/// \sa XSalsa20 struct Salsa20 : public Salsa20_Info, public SymmetricCipherDocumentation { typedef SymmetricCipherFinal >, Salsa20_Info> Encryption; typedef Encryption Decryption; }; -//! \class XSalsa20_Info -//! \brief XSalsa20 stream cipher information +/// \class XSalsa20_Info +/// \brief XSalsa20 stream cipher information struct XSalsa20_Info : public FixedKeyLength<32, SimpleKeyingInterface::UNIQUE_IV, 24> { static std::string StaticAlgorithmName() {return "XSalsa20";} }; -//! \class XSalsa20_Policy -//! \brief XSalsa20 stream cipher operation +/// \class XSalsa20_Policy +/// \brief XSalsa20 stream cipher operation class CRYPTOPP_NO_VTABLE XSalsa20_Policy : public Salsa20_Policy { public: @@ -71,10 +71,10 @@ protected: FixedSizeSecBlock m_key; }; -//! \class XSalsa20 -//! \brief XSalsa20 stream cipher -//! \details XSalsa20 provides a variable number of rounds: 8, 12 or 20. The default number of rounds is 20. -//! \sa XSalsa20 +/// \class XSalsa20 +/// \brief XSalsa20 stream cipher +/// \details XSalsa20 provides a variable number of rounds: 8, 12 or 20. The default number of rounds is 20. +/// \sa XSalsa20 struct XSalsa20 : public XSalsa20_Info, public SymmetricCipherDocumentation { typedef SymmetricCipherFinal >, XSalsa20_Info> Encryption; diff --git a/seal.h b/seal.h index edf53fac..c8a24951 100644 --- a/seal.h +++ b/seal.h @@ -1,7 +1,7 @@ // seal.h - originally written and placed in the public domain by Wei Dai -//! \file seal.h -//! \brief Classes for SEAL stream cipher +/// \file seal.h +/// \brief Classes for SEAL stream cipher #ifndef CRYPTOPP_SEAL_H #define CRYPTOPP_SEAL_H @@ -11,18 +11,18 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SEAL_Info -//! \brief SEAL stream cipher information -//! \tparam B Endianness of the stream cipher +/// \class SEAL_Info +/// \brief SEAL stream cipher information +/// \tparam B Endianness of the stream cipher template struct SEAL_Info : public FixedKeyLength<20, SimpleKeyingInterface::INTERNALLY_GENERATED_IV, 4> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return B::ToEnum() == LITTLE_ENDIAN_ORDER ? "SEAL-3.0-LE" : "SEAL-3.0-BE";} }; -//! \class SEAL_Policy -//! \brief SEAL stream cipher operation -//! \tparam B Endianness of the stream cipher +/// \class SEAL_Policy +/// \brief SEAL stream cipher operation +/// \tparam B Endianness of the stream cipher template class CRYPTOPP_NO_VTABLE SEAL_Policy : public AdditiveCipherConcretePolicy, public SEAL_Info { @@ -42,10 +42,10 @@ private: word32 m_outsideCounter, m_insideCounter; }; -//! \class SEAL -//! \brief SEAL stream cipher -//! \tparam B Endianness of the stream cipher -//! \sa SEAL +/// \class SEAL +/// \brief SEAL stream cipher +/// \tparam B Endianness of the stream cipher +/// \sa SEAL template struct SEAL : public SEAL_Info, public SymmetricCipherDocumentation { diff --git a/secblock.h b/secblock.h index f152e730..123546e2 100644 --- a/secblock.h +++ b/secblock.h @@ -1,7 +1,7 @@ // secblock.h - originally written and placed in the public domain by Wei Dai -//! \file secblock.h -//! \brief Classes and functions for secure memory allocations. +/// \file secblock.h +/// \brief Classes and functions for secure memory allocations. #ifndef CRYPTOPP_SECBLOCK_H #define CRYPTOPP_SECBLOCK_H @@ -22,9 +22,9 @@ NAMESPACE_BEGIN(CryptoPP) // ************** secure memory allocation *************** -//! \class AllocatorBase -//! \brief Base class for all allocators used by SecBlock -//! \tparam T the class or type +/// \class AllocatorBase +/// \brief Base class for all allocators used by SecBlock +/// \tparam T the class or type template class AllocatorBase { @@ -42,18 +42,18 @@ public: void construct(pointer p, const T& val) {new (p) T(val);} void destroy(pointer p) {CRYPTOPP_UNUSED(p); p->~T();} - //! \brief Returns the maximum number of elements the allocator can provide - //! \details ELEMS_MAX is the maximum number of elements the - //! Allocator can provide. The value of ELEMS_MAX is - //! SIZE_MAX/sizeof(T). std::numeric_limits was avoided - //! due to lack of constexpr-ness in C++03 and below. - //! \note In C++03 and below ELEMS_MAX is a static data member of type - //! size_type. In C++11 and above ELEMS_MAX is an enum - //! inheriting from size_type. In both cases ELEMS_MAX can be - //! used before objects are fully constructed, and it does not suffer the - //! limitations of class methods like max_size. - //! \sa Issue 346/CVE-2016-9939 - //! \since Crypto++ 6.0 + /// \brief Returns the maximum number of elements the allocator can provide + /// \details ELEMS_MAX is the maximum number of elements the + /// Allocator can provide. The value of ELEMS_MAX is + /// SIZE_MAX/sizeof(T). std::numeric_limits was avoided + /// due to lack of constexpr-ness in C++03 and below. + /// \note In C++03 and below ELEMS_MAX is a static data member of type + /// size_type. In C++11 and above ELEMS_MAX is an enum + /// inheriting from size_type. In both cases ELEMS_MAX can be + /// used before objects are fully constructed, and it does not suffer the + /// limitations of class methods like max_size. + /// \sa Issue 346/CVE-2016-9939 + /// \since Crypto++ 6.0 #if defined(CRYPTOPP_DOXYGEN_PROCESSING) static const size_type ELEMS_MAX = ...; #elif defined(CRYPTOPP_CXX11_ENUM) @@ -62,30 +62,30 @@ public: static const size_type ELEMS_MAX = SIZE_MAX/sizeof(T); #endif - //! \brief Returns the maximum number of elements the allocator can provide - //! \returns the maximum number of elements the allocator can provide - //! \details Internally, preprocessor macros are used rather than std::numeric_limits - //! because the latter is not a constexpr. Some compilers, like Clang, do not - //! optimize it well under all circumstances. Compilers like GCC, ICC and MSVC appear - //! to optimize it well in either form. + /// \brief Returns the maximum number of elements the allocator can provide + /// \returns the maximum number of elements the allocator can provide + /// \details Internally, preprocessor macros are used rather than std::numeric_limits + /// because the latter is not a constexpr. Some compilers, like Clang, do not + /// optimize it well under all circumstances. Compilers like GCC, ICC and MSVC appear + /// to optimize it well in either form. CRYPTOPP_CONSTEXPR size_type max_size() const {return ELEMS_MAX;} #if defined(CRYPTOPP_CXX11_VARIADIC_TEMPLATES) || defined(CRYPTOPP_DOXYGEN_PROCESSING) - //! \brief Constructs a new U using variadic arguments - //! \tparam U the type to be forwarded - //! \tparam Args the arguments to be forwarded - //! \param ptr pointer to type U - //! \param args variadic arguments - //! \details This is a C++11 feature. It is available when CRYPTOPP_CXX11_VARIADIC_TEMPLATES - //! is defined. The define is controlled by compiler versions detected in config.h. + /// \brief Constructs a new U using variadic arguments + /// \tparam U the type to be forwarded + /// \tparam Args the arguments to be forwarded + /// \param ptr pointer to type U + /// \param args variadic arguments + /// \details This is a C++11 feature. It is available when CRYPTOPP_CXX11_VARIADIC_TEMPLATES + /// is defined. The define is controlled by compiler versions detected in config.h. template void construct(U* ptr, Args&&... args) {::new ((void*)ptr) U(std::forward(args)...);} - //! \brief Destroys an U constructed with variadic arguments - //! \tparam U the type to be forwarded - //! \details This is a C++11 feature. It is available when CRYPTOPP_CXX11_VARIADIC_TEMPLATES - //! is defined. The define is controlled by compiler versions detected in config.h. + /// \brief Destroys an U constructed with variadic arguments + /// \tparam U the type to be forwarded + /// \details This is a C++11 feature. It is available when CRYPTOPP_CXX11_VARIADIC_TEMPLATES + /// is defined. The define is controlled by compiler versions detected in config.h. template void destroy(U* ptr) {if (ptr) ptr->~U();} @@ -93,21 +93,21 @@ public: protected: - //! \brief Verifies the allocator can satisfy a request based on size - //! \param size the size of the allocation, in elements - //! \throws InvalidArgument - //! \details CheckSize verifies the number of elements requested is valid. - //! \details If size is greater than max_size(), then InvalidArgument is thrown. - //! The library throws InvalidArgument if the size is too large to satisfy. - //! \details Internally, preprocessor macros are used rather than std::numeric_limits - //! because the latter is not a constexpr. Some compilers, like Clang, do not - //! optimize it well under all circumstances. Compilers like GCC, ICC and MSVC appear - //! to optimize it well in either form. - //! \details The sizeof(T) != 1 in the condition attempts to help the - //! compiler optimize the check for byte types. Coverity findings for - //! CONSTANT_EXPRESSION_RESULT were generated without it. For byte types, - //! size never exceeded ELEMS_MAX but the code was not removed. - //! \note size is the count of elements, and not the number of bytes + /// \brief Verifies the allocator can satisfy a request based on size + /// \param size the size of the allocation, in elements + /// \throws InvalidArgument + /// \details CheckSize verifies the number of elements requested is valid. + /// \details If size is greater than max_size(), then InvalidArgument is thrown. + /// The library throws InvalidArgument if the size is too large to satisfy. + /// \details Internally, preprocessor macros are used rather than std::numeric_limits + /// because the latter is not a constexpr. Some compilers, like Clang, do not + /// optimize it well under all circumstances. Compilers like GCC, ICC and MSVC appear + /// to optimize it well in either form. + /// \details The sizeof(T) != 1 in the condition attempts to help the + /// compiler optimize the check for byte types. Coverity findings for + /// CONSTANT_EXPRESSION_RESULT were generated without it. For byte types, + /// size never exceeded ELEMS_MAX but the code was not removed. + /// \note size is the count of elements, and not the number of bytes static void CheckSize(size_t size) { // Squash MSC C4100 warning for size. Also see commit 42b7c4ea5673. @@ -127,16 +127,16 @@ typedef typename AllocatorBase::const_pointer const_pointer;\ typedef typename AllocatorBase::reference reference;\ typedef typename AllocatorBase::const_reference const_reference; -//! \brief Reallocation function -//! \tparam T the class or type -//! \tparam A the class or type's allocator -//! \param alloc the allocator -//! \param oldPtr the previous allocation -//! \param oldSize the size of the previous allocation -//! \param newSize the new, requested size -//! \param preserve flag that indicates if the old allocation should be preserved -//! \note oldSize and newSize are the count of elements, and not the -//! number of bytes. +/// \brief Reallocation function +/// \tparam T the class or type +/// \tparam A the class or type's allocator +/// \param alloc the allocator +/// \param oldPtr the previous allocation +/// \param oldSize the size of the previous allocation +/// \param newSize the new, requested size +/// \param preserve flag that indicates if the old allocation should be preserved +/// \note oldSize and newSize are the count of elements, and not the +/// number of bytes. template typename A::pointer StandardReallocate(A& alloc, T *oldPtr, typename A::size_type oldSize, typename A::size_type newSize, bool preserve) { @@ -160,36 +160,36 @@ typename A::pointer StandardReallocate(A& alloc, T *oldPtr, typename A::size_typ } } -//! \class AllocatorWithCleanup -//! \brief Allocates a block of memory with cleanup -//! \tparam T class or type -//! \tparam T_Align16 boolean that determines whether allocations should be aligned on a 16-byte boundary -//! \details If T_Align16 is true, then AllocatorWithCleanup calls AlignedAllocate() -//! for memory allocations. If T_Align16 is false, then AllocatorWithCleanup() calls -//! UnalignedAllocate() for memory allocations. -//! \details Template parameter T_Align16 is effectively controlled by cryptlib.h and mirrors -//! CRYPTOPP_BOOL_ALIGN16. CRYPTOPP_BOOL_ALIGN16 is often used as the template parameter. +/// \class AllocatorWithCleanup +/// \brief Allocates a block of memory with cleanup +/// \tparam T class or type +/// \tparam T_Align16 boolean that determines whether allocations should be aligned on a 16-byte boundary +/// \details If T_Align16 is true, then AllocatorWithCleanup calls AlignedAllocate() +/// for memory allocations. If T_Align16 is false, then AllocatorWithCleanup() calls +/// UnalignedAllocate() for memory allocations. +/// \details Template parameter T_Align16 is effectively controlled by cryptlib.h and mirrors +/// CRYPTOPP_BOOL_ALIGN16. CRYPTOPP_BOOL_ALIGN16 is often used as the template parameter. template class AllocatorWithCleanup : public AllocatorBase { public: CRYPTOPP_INHERIT_ALLOCATOR_TYPES - //! \brief Allocates a block of memory - //! \param ptr the size of the allocation - //! \param size the size of the allocation, in elements - //! \returns a memory block - //! \throws InvalidArgument - //! \details allocate() first checks the size of the request. If it is non-0 - //! and less than max_size(), then an attempt is made to fulfill the request using either - //! AlignedAllocate() or UnalignedAllocate(). - //! \details AlignedAllocate() is used if T_Align16 is true. - //! UnalignedAllocate() used if T_Align16 is false. - //! \details This is the C++ *Placement New* operator. ptr is not used, and the function - //! CRYPTOPP_ASSERTs in Debug builds if ptr is non-NULL. - //! \sa CallNewHandler() for the methods used to recover from a failed - //! allocation attempt. - //! \note size is the count of elements, and not the number of bytes + /// \brief Allocates a block of memory + /// \param ptr the size of the allocation + /// \param size the size of the allocation, in elements + /// \returns a memory block + /// \throws InvalidArgument + /// \details allocate() first checks the size of the request. If it is non-0 + /// and less than max_size(), then an attempt is made to fulfill the request using either + /// AlignedAllocate() or UnalignedAllocate(). + /// \details AlignedAllocate() is used if T_Align16 is true. + /// UnalignedAllocate() used if T_Align16 is false. + /// \details This is the C++ *Placement New* operator. ptr is not used, and the function + /// CRYPTOPP_ASSERTs in Debug builds if ptr is non-NULL. + /// \sa CallNewHandler() for the methods used to recover from a failed + /// allocation attempt. + /// \note size is the count of elements, and not the number of bytes pointer allocate(size_type size, const void *ptr = NULLPTR) { CRYPTOPP_UNUSED(ptr); CRYPTOPP_ASSERT(ptr == NULLPTR); @@ -206,14 +206,14 @@ public: return (pointer)UnalignedAllocate(size*sizeof(T)); } - //! \brief Deallocates a block of memory - //! \param ptr the pointer for the allocation - //! \param size the size of the allocation, in elements - //! \details Internally, SecureWipeArray() is called before deallocating the memory. - //! Once the memory block is wiped or zeroized, AlignedDeallocate() or - //! UnalignedDeallocate() is called. - //! \details AlignedDeallocate() is used if T_Align16 is true. - //! UnalignedDeallocate() used if T_Align16 is false. + /// \brief Deallocates a block of memory + /// \param ptr the pointer for the allocation + /// \param size the size of the allocation, in elements + /// \details Internally, SecureWipeArray() is called before deallocating the memory. + /// Once the memory block is wiped or zeroized, AlignedDeallocate() or + /// UnalignedDeallocate() is called. + /// \details AlignedDeallocate() is used if T_Align16 is true. + /// UnalignedDeallocate() used if T_Align16 is false. void deallocate(void *ptr, size_type size) { // This will fire if SetMark(0) was called in the SecBlock @@ -229,32 +229,32 @@ public: UnalignedDeallocate(ptr); } - //! \brief Reallocates a block of memory - //! \param oldPtr the previous allocation - //! \param oldSize the size of the previous allocation - //! \param newSize the new, requested size - //! \param preserve flag that indicates if the old allocation should be preserved - //! \returns pointer to the new memory block - //! \details Internally, reallocate() calls StandardReallocate(). - //! \details If preserve is true, then index 0 is used to begin copying the - //! old memory block to the new one. If the block grows, then the old array - //! is copied in its entirety. If the block shrinks, then only newSize - //! elements are copied from the old block to the new one. - //! \note oldSize and newSize are the count of elements, and not the - //! number of bytes. + /// \brief Reallocates a block of memory + /// \param oldPtr the previous allocation + /// \param oldSize the size of the previous allocation + /// \param newSize the new, requested size + /// \param preserve flag that indicates if the old allocation should be preserved + /// \returns pointer to the new memory block + /// \details Internally, reallocate() calls StandardReallocate(). + /// \details If preserve is true, then index 0 is used to begin copying the + /// old memory block to the new one. If the block grows, then the old array + /// is copied in its entirety. If the block shrinks, then only newSize + /// elements are copied from the old block to the new one. + /// \note oldSize and newSize are the count of elements, and not the + /// number of bytes. pointer reallocate(T *oldPtr, size_type oldSize, size_type newSize, bool preserve) { CRYPTOPP_ASSERT((oldPtr && oldSize) || !(oldPtr || oldSize)); return StandardReallocate(*this, oldPtr, oldSize, newSize, preserve); } - //! \brief Template class memeber Rebind - //! \tparam U bound class or type - //! \details Rebind allows a container class to allocate a different type of object - //! to store elements. For example, a std::list will allocate std::list_node to - //! store elements in the list. - //! \details VS.NET STL enforces the policy of "All STL-compliant allocators - //! have to provide a template class member called rebind". + /// \brief Template class memeber Rebind + /// \tparam U bound class or type + /// \details Rebind allows a container class to allocate a different type of object + /// to store elements. For example, a std::list will allocate std::list_node to + /// store elements in the list. + /// \details VS.NET STL enforces the policy of "All STL-compliant allocators + /// have to provide a template class member called rebind". template struct rebind { typedef AllocatorWithCleanup other; }; #if _MSC_VER >= 1500 AllocatorWithCleanup() {} @@ -273,14 +273,14 @@ CRYPTOPP_DLL_TEMPLATE_CLASS AllocatorWithCleanup; // for Integer CRYPTOPP_DLL_TEMPLATE_CLASS AllocatorWithCleanup; // for Integer #endif -//! \class NullAllocator -//! \brief NULL allocator -//! \tparam T class or type -//! \details A NullAllocator is useful for fixed-size, stack based allocations -//! (i.e., static arrays used by FixedSizeAllocatorWithCleanup). -//! \details A NullAllocator always returns 0 for max_size(), and always returns -//! NULL for allocation requests. Though the allocator does not allocate at -//! runtime, it does perform a secure wipe or zeroization during cleanup. +/// \class NullAllocator +/// \brief NULL allocator +/// \tparam T class or type +/// \details A NullAllocator is useful for fixed-size, stack based allocations +/// (i.e., static arrays used by FixedSizeAllocatorWithCleanup). +/// \details A NullAllocator always returns 0 for max_size(), and always returns +/// NULL for allocation requests. Though the allocator does not allocate at +/// runtime, it does perform a secure wipe or zeroization during cleanup. template class NullAllocator : public AllocatorBase { @@ -307,39 +307,39 @@ public: //LCOV_EXCL_STOP }; -//! \class FixedSizeAllocatorWithCleanup -//! \brief Static secure memory block with cleanup -//! \tparam T class or type -//! \tparam S fixed-size of the stack-based memory block, in elements -//! \tparam T_Align16 boolean that determines whether allocations should be aligned on a 16-byte boundary -//! \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- -//! based allocation at compile time. The class can grow its memory -//! block at runtime if a suitable allocator is available. If size -//! grows beyond S and a suitable allocator is available, then the -//! statically allocated array is obsoleted. -//! \note This allocator can't be used with standard collections because -//! they require that all objects of the same allocator type are equivalent. +/// \class FixedSizeAllocatorWithCleanup +/// \brief Static secure memory block with cleanup +/// \tparam T class or type +/// \tparam S fixed-size of the stack-based memory block, in elements +/// \tparam T_Align16 boolean that determines whether allocations should be aligned on a 16-byte boundary +/// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- +/// based allocation at compile time. The class can grow its memory +/// block at runtime if a suitable allocator is available. If size +/// grows beyond S and a suitable allocator is available, then the +/// statically allocated array is obsoleted. +/// \note This allocator can't be used with standard collections because +/// they require that all objects of the same allocator type are equivalent. template , bool T_Align16 = false> class FixedSizeAllocatorWithCleanup : public AllocatorBase { public: CRYPTOPP_INHERIT_ALLOCATOR_TYPES - //! \brief Constructs a FixedSizeAllocatorWithCleanup + /// \brief Constructs a FixedSizeAllocatorWithCleanup FixedSizeAllocatorWithCleanup() : m_allocated(false) {} - //! \brief Allocates a block of memory - //! \param size the count elements in the memory block - //! \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack-based - //! allocation at compile time. If size is less than or equal to - //! S, then a pointer to the static array is returned. - //! \details The class can grow its memory block at runtime if a suitable - //! allocator is available. If size grows beyond S and a suitable - //! allocator is available, then the statically allocated array is - //! obsoleted. If a suitable allocator is not available, as with a - //! NullAllocator, then the function returns NULL and a runtime error - //! eventually occurs. - //! \sa reallocate(), SecBlockWithHint + /// \brief Allocates a block of memory + /// \param size the count elements in the memory block + /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack-based + /// allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. + /// \details The class can grow its memory block at runtime if a suitable + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. + /// \sa reallocate(), SecBlockWithHint pointer allocate(size_type size) { CRYPTOPP_ASSERT(IsAlignedOn(m_array, 8)); @@ -353,19 +353,19 @@ public: return m_fallbackAllocator.allocate(size); } - //! \brief Allocates a block of memory - //! \param size the count elements in the memory block - //! \param hint an unused hint - //! \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- - //! based allocation at compile time. If size is less than or equal to - //! S, then a pointer to the static array is returned. - //! \details The class can grow its memory block at runtime if a suitable - //! allocator is available. If size grows beyond S and a suitable - //! allocator is available, then the statically allocated array is - //! obsoleted. If a suitable allocator is not available, as with a - //! NullAllocator, then the function returns NULL and a runtime error - //! eventually occurs. - //! \sa reallocate(), SecBlockWithHint + /// \brief Allocates a block of memory + /// \param size the count elements in the memory block + /// \param hint an unused hint + /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- + /// based allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. + /// \details The class can grow its memory block at runtime if a suitable + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. + /// \sa reallocate(), SecBlockWithHint pointer allocate(size_type size, const void *hint) { if (size <= S && !m_allocated) @@ -377,14 +377,14 @@ public: return m_fallbackAllocator.allocate(size, hint); } - //! \brief Deallocates a block of memory - //! \param ptr a pointer to the memory block to deallocate - //! \param size the count elements in the memory block - //! \details The memory block is wiped or zeroized before deallocation. - //! If the statically allocated memory block is active, then no - //! additional actions are taken after the wipe. - //! \details If a dynamic memory block is active, then the pointer and - //! size are passed to the allocator for deallocation. + /// \brief Deallocates a block of memory + /// \param ptr a pointer to the memory block to deallocate + /// \param size the count elements in the memory block + /// \details The memory block is wiped or zeroized before deallocation. + /// If the statically allocated memory block is active, then no + /// additional actions are taken after the wipe. + /// \details If a dynamic memory block is active, then the pointer and + /// size are passed to the allocator for deallocation. void deallocate(void *ptr, size_type size) { if (ptr == GetAlignedArray()) @@ -398,23 +398,23 @@ public: m_fallbackAllocator.deallocate(ptr, size); } - //! \brief Reallocates a block of memory - //! \param oldPtr the previous allocation - //! \param oldSize the size of the previous allocation - //! \param newSize the new, requested size - //! \param preserve flag that indicates if the old allocation should be preserved - //! \returns pointer to the new memory block - //! \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- - //! based allocation at compile time. If size is less than or equal to - //! S, then a pointer to the static array is returned. - //! \details The class can grow its memory block at runtime if a suitable - //! allocator is available. If size grows beyond S and a suitable - //! allocator is available, then the statically allocated array is - //! obsoleted. If a suitable allocator is not available, as with a - //! NullAllocator, then the function returns NULL and a runtime error - //! eventually occurs. - //! \note size is the count of elements, and not the number of bytes. - //! \sa reallocate(), SecBlockWithHint + /// \brief Reallocates a block of memory + /// \param oldPtr the previous allocation + /// \param oldSize the size of the previous allocation + /// \param newSize the new, requested size + /// \param preserve flag that indicates if the old allocation should be preserved + /// \returns pointer to the new memory block + /// \details FixedSizeAllocatorWithCleanup provides a fixed-size, stack- + /// based allocation at compile time. If size is less than or equal to + /// S, then a pointer to the static array is returned. + /// \details The class can grow its memory block at runtime if a suitable + /// allocator is available. If size grows beyond S and a suitable + /// allocator is available, then the statically allocated array is + /// obsoleted. If a suitable allocator is not available, as with a + /// NullAllocator, then the function returns NULL and a runtime error + /// eventually occurs. + /// \note size is the count of elements, and not the number of bytes. + /// \sa reallocate(), SecBlockWithHint pointer reallocate(pointer oldPtr, size_type oldSize, size_type newSize, bool preserve) { if (oldPtr == GetAlignedArray() && newSize <= S) @@ -451,10 +451,10 @@ private: bool m_allocated; }; -//! \class SecBlock -//! \brief Secure memory block with allocator and cleanup -//! \tparam T a class or type -//! \tparam A AllocatorWithCleanup derived class for allocation and cleanup +/// \class SecBlock +/// \brief Secure memory block with allocator and cleanup +/// \tparam T a class or type +/// \tparam A AllocatorWithCleanup derived class for allocation and cleanup template > class SecBlock { @@ -464,18 +464,18 @@ public: typedef typename A::const_pointer const_iterator; typedef typename A::size_type size_type; - //! \brief Returns the maximum number of elements the block can hold - //! \details ELEMS_MAX is the maximum number of elements the - //! SecBlock can hold. The value of ELEMS_MAX is - //! SIZE_MAX/sizeof(T). std::numeric_limits was avoided - //! due to lack of constexpr-ness in C++03 and below. - //! \note In C++03 and below ELEMS_MAX is a static data member of type - //! size_type. In C++11 and above ELEMS_MAX is an enum - //! inheriting from size_type. In both cases ELEMS_MAX can be - //! used before objects are fully constructed, and it does not suffer the - //! limitations of class methods like max_size. - //! \sa Issue 346/CVE-2016-9939 - //! \since Crypto++ 6.0 + /// \brief Returns the maximum number of elements the block can hold + /// \details ELEMS_MAX is the maximum number of elements the + /// SecBlock can hold. The value of ELEMS_MAX is + /// SIZE_MAX/sizeof(T). std::numeric_limits was avoided + /// due to lack of constexpr-ness in C++03 and below. + /// \note In C++03 and below ELEMS_MAX is a static data member of type + /// size_type. In C++11 and above ELEMS_MAX is an enum + /// inheriting from size_type. In both cases ELEMS_MAX can be + /// used before objects are fully constructed, and it does not suffer the + /// limitations of class methods like max_size. + /// \sa Issue 346/CVE-2016-9939 + /// \since Crypto++ 6.0 #if defined(CRYPTOPP_DOXYGEN_PROCESSING) static const size_type ELEMS_MAX = ...; #elif defined(CRYPTOPP_CXX11_ENUM) @@ -484,31 +484,31 @@ public: static const size_type ELEMS_MAX = SIZE_MAX/sizeof(T); #endif - //! \brief Construct a SecBlock with space for size elements. - //! \param size the size of the allocation, in elements - //! \throws std::bad_alloc - //! \details The elements are not initialized. - //! \note size is the count of elements, and not the number of bytes + /// \brief Construct a SecBlock with space for size elements. + /// \param size the size of the allocation, in elements + /// \throws std::bad_alloc + /// \details The elements are not initialized. + /// \note size is the count of elements, and not the number of bytes explicit SecBlock(size_type size=0) : m_mark(ELEMS_MAX), m_size(size), m_ptr(m_alloc.allocate(size, NULLPTR)) { } - //! \brief Copy construct a SecBlock from another SecBlock - //! \param t the other SecBlock - //! \throws std::bad_alloc + /// \brief Copy construct a SecBlock from another SecBlock + /// \param t the other SecBlock + /// \throws std::bad_alloc SecBlock(const SecBlock &t) : m_mark(t.m_mark), m_size(t.m_size), m_ptr(m_alloc.allocate(t.m_size, NULLPTR)) { CRYPTOPP_ASSERT((!t.m_ptr && !m_size) || (t.m_ptr && m_size)); if (t.m_ptr) {memcpy_s(m_ptr, m_size*sizeof(T), t.m_ptr, t.m_size*sizeof(T));} } - //! \brief Construct a SecBlock from an array of elements. - //! \param ptr a pointer to an array of T - //! \param len the number of elements in the memory block - //! \throws std::bad_alloc - //! \details If ptr!=NULL and len!=0, then the block is initialized from the pointer - //! ptr. If ptr==NULL and len!=0, then the block is initialized to 0. - //! Otherwise, the block is empty and not initialized. - //! \note size is the count of elements, and not the number of bytes + /// \brief Construct a SecBlock from an array of elements. + /// \param ptr a pointer to an array of T + /// \param len the number of elements in the memory block + /// \throws std::bad_alloc + /// \details If ptr!=NULL and len!=0, then the block is initialized from the pointer + /// ptr. If ptr==NULL and len!=0, then the block is initialized to 0. + /// Otherwise, the block is empty and not initialized. + /// \note size is the count of elements, and not the number of bytes SecBlock(const T *ptr, size_type len) : m_mark(ELEMS_MAX), m_size(len), m_ptr(m_alloc.allocate(len, NULLPTR)) { CRYPTOPP_ASSERT((!m_ptr && !m_size) || (m_ptr && m_size)); @@ -536,77 +536,77 @@ public: {return m_ptr;} #endif - //! \brief Provides an iterator pointing to the first element in the memory block - //! \returns iterator pointing to the first element in the memory block + /// \brief Provides an iterator pointing to the first element in the memory block + /// \returns iterator pointing to the first element in the memory block iterator begin() {return m_ptr;} - //! \brief Provides a constant iterator pointing to the first element in the memory block - //! \returns constant iterator pointing to the first element in the memory block + /// \brief Provides a constant iterator pointing to the first element in the memory block + /// \returns constant iterator pointing to the first element in the memory block const_iterator begin() const {return m_ptr;} - //! \brief Provides an iterator pointing beyond the last element in the memory block - //! \returns iterator pointing beyond the last element in the memory block + /// \brief Provides an iterator pointing beyond the last element in the memory block + /// \returns iterator pointing beyond the last element in the memory block iterator end() {return m_ptr+m_size;} - //! \brief Provides a constant iterator pointing beyond the last element in the memory block - //! \returns constant iterator pointing beyond the last element in the memory block + /// \brief Provides a constant iterator pointing beyond the last element in the memory block + /// \returns constant iterator pointing beyond the last element in the memory block const_iterator end() const {return m_ptr+m_size;} - //! \brief Provides a pointer to the first element in the memory block - //! \returns pointer to the first element in the memory block + /// \brief Provides a pointer to the first element in the memory block + /// \returns pointer to the first element in the memory block typename A::pointer data() {return m_ptr;} - //! \brief Provides a pointer to the first element in the memory block - //! \returns constant pointer to the first element in the memory block + /// \brief Provides a pointer to the first element in the memory block + /// \returns constant pointer to the first element in the memory block typename A::const_pointer data() const {return m_ptr;} - //! \brief Provides the count of elements in the SecBlock - //! \returns number of elements in the memory block - //! \note the return value is the count of elements, and not the number of bytes + /// \brief Provides the count of elements in the SecBlock + /// \returns number of elements in the memory block + /// \note the return value is the count of elements, and not the number of bytes size_type size() const {return m_size;} - //! \brief Determines if the SecBlock is empty - //! \returns true if number of elements in the memory block is 0, false otherwise + /// \brief Determines if the SecBlock is empty + /// \returns true if number of elements in the memory block is 0, false otherwise bool empty() const {return m_size == 0;} - //! \brief Provides a byte pointer to the first element in the memory block - //! \returns byte pointer to the first element in the memory block + /// \brief Provides a byte pointer to the first element in the memory block + /// \returns byte pointer to the first element in the memory block byte * BytePtr() {return (byte *)m_ptr;} - //! \brief Return a byte pointer to the first element in the memory block - //! \returns constant byte pointer to the first element in the memory block + /// \brief Return a byte pointer to the first element in the memory block + /// \returns constant byte pointer to the first element in the memory block const byte * BytePtr() const {return (const byte *)m_ptr;} - //! \brief Provides the number of bytes in the SecBlock - //! \return the number of bytes in the memory block - //! \note the return value is the number of bytes, and not count of elements. + /// \brief Provides the number of bytes in the SecBlock + /// \return the number of bytes in the memory block + /// \note the return value is the number of bytes, and not count of elements. size_type SizeInBytes() const {return m_size*sizeof(T);} - //! \brief Sets the number of elements to zeroize - //! \param count the number of elements - //! \details SetMark is a remediation for Issue 346/CVE-2016-9939 while - //! preserving the streaming interface. The count controls the number of - //! elements zeroized, which can be less than size or 0. - //! \details An internal variable, m_mark, is initialized to the maximum number - //! of elements. The maximum number of elements is ELEMS_MAX. Deallocation - //! triggers a zeroization, and the number of elements zeroized is - //! STDMIN(m_size, m_mark). After zeroization, the memory is returned to the - //! system. - //! \details The ASN.1 decoder uses SetMark() to set the element count to 0 - //! before throwing an exception. In this case, the attacker provides a large - //! BER encoded length (say 64MB) but only a small number of content octets - //! (say 16). If the allocator zeroized all 64MB, then a transient DoS could - //! occur as CPU cycles are spent zeroizing unintialized memory. - //! \details Generally speaking, any operation which changes the size of the SecBlock - //! results in the mark being reset to ELEMS_MAX. In particular, if Assign(), - //! New(), Grow(), CleanNew(), CleanGrow() are called, then the count is reset to - //! ELEMS_MAX. The list is not exhaustive. - //! \since Crypto++ 6.0 - //! \sa Issue 346/CVE-2016-9939 + /// \brief Sets the number of elements to zeroize + /// \param count the number of elements + /// \details SetMark is a remediation for Issue 346/CVE-2016-9939 while + /// preserving the streaming interface. The count controls the number of + /// elements zeroized, which can be less than size or 0. + /// \details An internal variable, m_mark, is initialized to the maximum number + /// of elements. The maximum number of elements is ELEMS_MAX. Deallocation + /// triggers a zeroization, and the number of elements zeroized is + /// STDMIN(m_size, m_mark). After zeroization, the memory is returned to the + /// system. + /// \details The ASN.1 decoder uses SetMark() to set the element count to 0 + /// before throwing an exception. In this case, the attacker provides a large + /// BER encoded length (say 64MB) but only a small number of content octets + /// (say 16). If the allocator zeroized all 64MB, then a transient DoS could + /// occur as CPU cycles are spent zeroizing unintialized memory. + /// \details Generally speaking, any operation which changes the size of the SecBlock + /// results in the mark being reset to ELEMS_MAX. In particular, if Assign(), + /// New(), Grow(), CleanNew(), CleanGrow() are called, then the count is reset to + /// ELEMS_MAX. The list is not exhaustive. + /// \since Crypto++ 6.0 + /// \sa Issue 346/CVE-2016-9939 void SetMark(size_t count) {m_mark = count;} - //! \brief Set contents and size from an array - //! \param ptr a pointer to an array of T - //! \param len the number of elements in the memory block - //! \details If the memory block is reduced in size, then the reclaimed memory is set to 0. - //! Assign() resets the element count after the previous block is zeroized. + /// \brief Set contents and size from an array + /// \param ptr a pointer to an array of T + /// \param len the number of elements in the memory block + /// \details If the memory block is reduced in size, then the reclaimed memory is set to 0. + /// Assign() resets the element count after the previous block is zeroized. void Assign(const T *ptr, size_type len) { New(len); @@ -615,11 +615,11 @@ public: m_mark = ELEMS_MAX; } - //! \brief Set contents from a value - //! \param count the number of values to copy - //! \param value the value, repeated count times - //! \details If the memory block is reduced in size, then the reclaimed memory is set to 0. - //! Assign() resets the element count after the previous block is zeroized. + /// \brief Set contents from a value + /// \param count the number of values to copy + /// \param value the value, repeated count times + /// \details If the memory block is reduced in size, then the reclaimed memory is set to 0. + /// Assign() resets the element count after the previous block is zeroized. void Assign(size_type count, T value) { New(count); @@ -629,12 +629,12 @@ public: m_mark = ELEMS_MAX; } - //! \brief Copy contents from another SecBlock - //! \param t the other SecBlock - //! \details Assign checks for self assignment. - //! \details If the memory block is reduced in size, then the reclaimed memory is set to 0. - //! If an assignment occurs, then Assign() resets the element count after the previous block - //! is zeroized. + /// \brief Copy contents from another SecBlock + /// \param t the other SecBlock + /// \details Assign checks for self assignment. + /// \details If the memory block is reduced in size, then the reclaimed memory is set to 0. + /// If an assignment occurs, then Assign() resets the element count after the previous block + /// is zeroized. void Assign(const SecBlock &t) { if (this != &t) @@ -646,12 +646,12 @@ public: m_mark = ELEMS_MAX; } - //! \brief Assign contents from another SecBlock - //! \param t the other SecBlock - //! \details Internally, operator=() calls Assign(). - //! \details If the memory block is reduced in size, then the reclaimed memory is set to 0. - //! If an assignment occurs, then Assign() resets the element count after the previous block - //! is zeroized. + /// \brief Assign contents from another SecBlock + /// \param t the other SecBlock + /// \details Internally, operator=() calls Assign(). + /// \details If the memory block is reduced in size, then the reclaimed memory is set to 0. + /// If an assignment occurs, then Assign() resets the element count after the previous block + /// is zeroized. SecBlock& operator=(const SecBlock &t) { // Assign guards for self-assignment @@ -659,9 +659,9 @@ public: return *this; } - //! \brief Append contents from another SecBlock - //! \param t the other SecBlock - //! \details Internally, this SecBlock calls Grow and then appends t. + /// \brief Append contents from another SecBlock + /// \param t the other SecBlock + /// \details Internally, this SecBlock calls Grow and then appends t. SecBlock& operator+=(const SecBlock &t) { CRYPTOPP_ASSERT((!t.m_ptr && !t.m_size) || (t.m_ptr && t.m_size)); @@ -683,10 +683,10 @@ public: return *this; } - //! \brief Construct a SecBlock from this and another SecBlock - //! \param t the other SecBlock - //! \returns a newly constructed SecBlock that is a conacentation of this and t - //! \details Internally, a new SecBlock is created from this and a concatenation of t. + /// \brief Construct a SecBlock from this and another SecBlock + /// \param t the other SecBlock + /// \returns a newly constructed SecBlock that is a conacentation of this and t + /// \details Internally, a new SecBlock is created from this and a concatenation of t. SecBlock operator+(const SecBlock &t) { CRYPTOPP_ASSERT((!m_ptr && !m_size) || (m_ptr && m_size)); @@ -699,38 +699,38 @@ public: return result; } - //! \brief Bitwise compare two SecBlocks - //! \param t the other SecBlock - //! \returns true if the size and bits are equal, false otherwise - //! \details Uses a constant time compare if the arrays are equal size. The constant time - //! compare is VerifyBufsEqual() found in misc.h. - //! \sa operator!=() + /// \brief Bitwise compare two SecBlocks + /// \param t the other SecBlock + /// \returns true if the size and bits are equal, false otherwise + /// \details Uses a constant time compare if the arrays are equal size. The constant time + /// compare is VerifyBufsEqual() found in misc.h. + /// \sa operator!=() bool operator==(const SecBlock &t) const { return m_size == t.m_size && VerifyBufsEqual(reinterpret_cast(m_ptr), reinterpret_cast(t.m_ptr), m_size*sizeof(T)); } - //! \brief Bitwise compare two SecBlocks - //! \param t the other SecBlock - //! \returns true if the size and bits are equal, false otherwise - //! \details Uses a constant time compare if the arrays are equal size. The constant time - //! compare is VerifyBufsEqual() found in misc.h. - //! \details Internally, operator!=() returns the inverse of operator==(). - //! \sa operator==() + /// \brief Bitwise compare two SecBlocks + /// \param t the other SecBlock + /// \returns true if the size and bits are equal, false otherwise + /// \details Uses a constant time compare if the arrays are equal size. The constant time + /// compare is VerifyBufsEqual() found in misc.h. + /// \details Internally, operator!=() returns the inverse of operator==(). + /// \sa operator==() bool operator!=(const SecBlock &t) const { return !operator==(t); } - //! \brief Change size without preserving contents - //! \param newSize the new size of the memory block - //! \details Old content is not preserved. If the memory block is reduced in size, - //! then the reclaimed memory is set to 0. If the memory block grows in size, then - //! the new memory is not initialized. New() resets the element count after the - //! previous block is zeroized. - //! \details Internally, this SecBlock calls reallocate(). - //! \sa New(), CleanNew(), Grow(), CleanGrow(), resize() + /// \brief Change size without preserving contents + /// \param newSize the new size of the memory block + /// \details Old content is not preserved. If the memory block is reduced in size, + /// then the reclaimed memory is set to 0. If the memory block grows in size, then + /// the new memory is not initialized. New() resets the element count after the + /// previous block is zeroized. + /// \details Internally, this SecBlock calls reallocate(). + /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void New(size_type newSize) { m_ptr = m_alloc.reallocate(m_ptr, m_size, newSize, false); @@ -738,14 +738,14 @@ public: m_mark = ELEMS_MAX; } - //! \brief Change size without preserving contents - //! \param newSize the new size of the memory block - //! \details Old content is not preserved. If the memory block is reduced in size, - //! then the reclaimed content is set to 0. If the memory block grows in size, then - //! the new memory is initialized to 0. CleanNew() resets the element count after the - //! previous block is zeroized. - //! \details Internally, this SecBlock calls New(). - //! \sa New(), CleanNew(), Grow(), CleanGrow(), resize() + /// \brief Change size without preserving contents + /// \param newSize the new size of the memory block + /// \details Old content is not preserved. If the memory block is reduced in size, + /// then the reclaimed content is set to 0. If the memory block grows in size, then + /// the new memory is initialized to 0. CleanNew() resets the element count after the + /// previous block is zeroized. + /// \details Internally, this SecBlock calls New(). + /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void CleanNew(size_type newSize) { New(newSize); @@ -753,14 +753,14 @@ public: m_mark = ELEMS_MAX; } - //! \brief Change size and preserve contents - //! \param newSize the new size of the memory block - //! \details Old content is preserved. New content is not initialized. - //! \details Internally, this SecBlock calls reallocate() when size must increase. If the - //! size does not increase, then Grow() does not take action. If the size must - //! change, then use resize(). Grow() resets the element count after the - //! previous block is zeroized. - //! \sa New(), CleanNew(), Grow(), CleanGrow(), resize() + /// \brief Change size and preserve contents + /// \param newSize the new size of the memory block + /// \details Old content is preserved. New content is not initialized. + /// \details Internally, this SecBlock calls reallocate() when size must increase. If the + /// size does not increase, then Grow() does not take action. If the size must + /// change, then use resize(). Grow() resets the element count after the + /// previous block is zeroized. + /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void Grow(size_type newSize) { if (newSize > m_size) @@ -771,14 +771,14 @@ public: m_mark = ELEMS_MAX; } - //! \brief Change size and preserve contents - //! \param newSize the new size of the memory block - //! \details Old content is preserved. New content is initialized to 0. - //! \details Internally, this SecBlock calls reallocate() when size must increase. If the - //! size does not increase, then CleanGrow() does not take action. If the size must - //! change, then use resize(). CleanGrow() resets the element count after the - //! previous block is zeroized. - //! \sa New(), CleanNew(), Grow(), CleanGrow(), resize() + /// \brief Change size and preserve contents + /// \param newSize the new size of the memory block + /// \details Old content is preserved. New content is initialized to 0. + /// \details Internally, this SecBlock calls reallocate() when size must increase. If the + /// size does not increase, then CleanGrow() does not take action. If the size must + /// change, then use resize(). CleanGrow() resets the element count after the + /// previous block is zeroized. + /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void CleanGrow(size_type newSize) { if (newSize > m_size) @@ -790,13 +790,13 @@ public: m_mark = ELEMS_MAX; } - //! \brief Change size and preserve contents - //! \param newSize the new size of the memory block - //! \details Old content is preserved. If the memory block grows in size, then - //! new memory is not initialized. resize() resets the element count after - //! the previous block is zeroized. - //! \details Internally, this SecBlock calls reallocate(). - //! \sa New(), CleanNew(), Grow(), CleanGrow(), resize() + /// \brief Change size and preserve contents + /// \param newSize the new size of the memory block + /// \details Old content is preserved. If the memory block grows in size, then + /// new memory is not initialized. resize() resets the element count after + /// the previous block is zeroized. + /// \details Internally, this SecBlock calls reallocate(). + /// \sa New(), CleanNew(), Grow(), CleanGrow(), resize() void resize(size_type newSize) { m_ptr = m_alloc.reallocate(m_ptr, m_size, newSize, true); @@ -804,9 +804,9 @@ public: m_mark = ELEMS_MAX; } - //! \brief Swap contents with another SecBlock - //! \param b the other SecBlock - //! \details Internally, std::swap() is called on m_alloc, m_size and m_ptr. + /// \brief Swap contents with another SecBlock + /// \param b the other SecBlock + /// \details Internally, std::swap() is called on m_alloc, m_size and m_ptr. void swap(SecBlock &b) { // Swap must occur on the allocator in case its FixedSize that spilled into the heap. @@ -823,14 +823,14 @@ protected: }; #ifdef CRYPTOPP_DOXYGEN_PROCESSING -//! \class SecByteBlock -//! \brief \ref SecBlock "SecBlock" typedef. +/// \class SecByteBlock +/// \brief \ref SecBlock "SecBlock" typedef. class SecByteBlock : public SecBlock {}; -//! \class SecWordBlock -//! \brief \ref SecBlock "SecBlock" typedef. +/// \class SecWordBlock +/// \brief \ref SecBlock "SecBlock" typedef. class SecWordBlock : public SecBlock {}; -//! \class AlignedSecByteBlock -//! \brief SecBlock using \ref AllocatorWithCleanup "AllocatorWithCleanup" typedef +/// \class AlignedSecByteBlock +/// \brief SecBlock using \ref AllocatorWithCleanup "AllocatorWithCleanup" typedef class AlignedSecByteBlock : public SecBlock > {}; #else typedef SecBlock SecByteBlock; @@ -841,39 +841,39 @@ typedef SecBlock > AlignedSecByteBlock; // No need for move semantics on derived class *if* the class does not add any // data members; see http://stackoverflow.com/q/31755703, and Rule of {0|3|5}. -//! \class FixedSizeSecBlock -//! \brief Fixed size stack-based SecBlock -//! \tparam T class or type -//! \tparam S fixed-size of the stack-based memory block, in elements -//! \tparam A AllocatorBase derived class for allocation and cleanup +/// \class FixedSizeSecBlock +/// \brief Fixed size stack-based SecBlock +/// \tparam T class or type +/// \tparam S fixed-size of the stack-based memory block, in elements +/// \tparam A AllocatorBase derived class for allocation and cleanup template > class FixedSizeSecBlock : public SecBlock { public: - //! \brief Construct a FixedSizeSecBlock + /// \brief Construct a FixedSizeSecBlock explicit FixedSizeSecBlock() : SecBlock(S) {} }; -//! \class FixedSizeAlignedSecBlock -//! \brief Fixed size stack-based SecBlock with 16-byte alignment -//! \tparam T class or type -//! \tparam S fixed-size of the stack-based memory block, in elements -//! \tparam T_Align16 boolean that determines whether allocations should be aligned on a 16-byte boundary +/// \class FixedSizeAlignedSecBlock +/// \brief Fixed size stack-based SecBlock with 16-byte alignment +/// \tparam T class or type +/// \tparam S fixed-size of the stack-based memory block, in elements +/// \tparam T_Align16 boolean that determines whether allocations should be aligned on a 16-byte boundary template class FixedSizeAlignedSecBlock : public FixedSizeSecBlock, T_Align16> > { }; -//! \class SecBlockWithHint -//! \brief Stack-based SecBlock that grows into the heap -//! \tparam T class or type -//! \tparam S fixed-size of the stack-based memory block, in elements -//! \tparam A AllocatorBase derived class for allocation and cleanup +/// \class SecBlockWithHint +/// \brief Stack-based SecBlock that grows into the heap +/// \tparam T class or type +/// \tparam S fixed-size of the stack-based memory block, in elements +/// \tparam A AllocatorBase derived class for allocation and cleanup template > > class SecBlockWithHint : public SecBlock { public: - //! construct a SecBlockWithHint with a count of elements + /// construct a SecBlockWithHint with a count of elements explicit SecBlockWithHint(size_t size) : SecBlock(size) {} }; diff --git a/seckey.h b/seckey.h index 088bf754..74e1ac15 100644 --- a/seckey.h +++ b/seckey.h @@ -1,7 +1,7 @@ // seckey.h - originally written and placed in the public domain by Wei Dai -//! \file seckey.h -//! \brief Classes and functions for implementing secret key algorithms. +/// \file seckey.h +/// \brief Classes and functions for implementing secret key algorithms. #ifndef CRYPTOPP_SECKEY_H #define CRYPTOPP_SECKEY_H @@ -25,42 +25,42 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Inverts the cipher's direction -//! \param dir the cipher's direction -//! \returns DECRYPTION if \ref CipherDir "dir" is ENCRYPTION, DECRYPTION otherwise +/// \brief Inverts the cipher's direction +/// \param dir the cipher's direction +/// \returns DECRYPTION if \ref CipherDir "dir" is ENCRYPTION, DECRYPTION otherwise inline CipherDir ReverseCipherDir(CipherDir dir) { return (dir == ENCRYPTION) ? DECRYPTION : ENCRYPTION; } -//! \class FixedBlockSize -//! \brief Inherited by algorithms with fixed block size -//! \tparam N the blocksize of the algorithm +/// \class FixedBlockSize +/// \brief Inherited by algorithms with fixed block size +/// \tparam N the blocksize of the algorithm template class FixedBlockSize { public: - //! \brief The block size of the algorithm provided as a constant. + /// \brief The block size of the algorithm provided as a constant. CRYPTOPP_CONSTANT(BLOCKSIZE = N) - //! \brief The default blocksize for the algorithm provided as a constant. + /// \brief The default blocksize for the algorithm provided as a constant. CRYPTOPP_CONSTANT(DEFAULT_BLOCKSIZE = N) - //! \brief The minimum blocksize for the algorithm provided as a constant. + /// \brief The minimum blocksize for the algorithm provided as a constant. CRYPTOPP_CONSTANT(MIN_BLOCKSIZE = N) - //! \brief The maximum blocksize for the algorithm provided as a constant. + /// \brief The maximum blocksize for the algorithm provided as a constant. CRYPTOPP_CONSTANT(MAX_BLOCKSIZE = N) - //! \brief The default block size for the algorithm provided by a static function. - //! \param blocksize the block size, in bytes - //! \details The default implementation returns BLOCKSIZE. blocksize is unused - //! in the default implementation. + /// \brief The default block size for the algorithm provided by a static function. + /// \param blocksize the block size, in bytes + /// \details The default implementation returns BLOCKSIZE. blocksize is unused + /// in the default implementation. CRYPTOPP_STATIC_CONSTEXPR size_t CRYPTOPP_API StaticGetValidBlockSize(size_t blocksize) { return CRYPTOPP_UNUSED(blocksize), static_cast(BLOCKSIZE); } - //! \brief The default block size under a key provided by a static function. - //! \param keylength the size of the key, in bytes - //! \param blocksize the block size, in bytes - //! \details The default implementation returns BLOCKSIZE. blocksize is unused - //! in the default implementation. + /// \brief The default block size under a key provided by a static function. + /// \param keylength the size of the key, in bytes + /// \param blocksize the block size, in bytes + /// \details The default implementation returns BLOCKSIZE. blocksize is unused + /// in the default implementation. CRYPTOPP_STATIC_CONSTEXPR size_t CRYPTOPP_API StaticGetValidBlockSize(size_t keylength, size_t blocksize) { return CRYPTOPP_UNUSED(keylength), CRYPTOPP_UNUSED(blocksize), static_cast(BLOCKSIZE); @@ -69,47 +69,47 @@ public: // ************** rounds *************** -//! \class FixedRounds -//! \brief Inherited by algorithms with fixed number of rounds -//! \tparam R the number of rounds used by the algorithm +/// \class FixedRounds +/// \brief Inherited by algorithms with fixed number of rounds +/// \tparam R the number of rounds used by the algorithm template class FixedRounds { public: - //! \brief The number of rounds for the algorithm provided as a constant. + /// \brief The number of rounds for the algorithm provided as a constant. CRYPTOPP_CONSTANT(ROUNDS = R) }; -//! \class VariableRounds -//! \brief Inherited by algorithms with variable number of rounds -//! \tparam D Default number of rounds -//! \tparam N Minimum number of rounds -//! \tparam M Maximum number of rounds +/// \class VariableRounds +/// \brief Inherited by algorithms with variable number of rounds +/// \tparam D Default number of rounds +/// \tparam N Minimum number of rounds +/// \tparam M Maximum number of rounds template // use INT_MAX here because enums are treated as signed ints class VariableRounds { public: - //! \brief The default number of rounds for the algorithm provided as a constant. + /// \brief The default number of rounds for the algorithm provided as a constant. CRYPTOPP_CONSTANT(DEFAULT_ROUNDS = D) - //! \brief The minimum number of rounds for the algorithm provided as a constant. + /// \brief The minimum number of rounds for the algorithm provided as a constant. CRYPTOPP_CONSTANT(MIN_ROUNDS = N) - //! \brief The maximum number of rounds for the algorithm provided as a constant. + /// \brief The maximum number of rounds for the algorithm provided as a constant. CRYPTOPP_CONSTANT(MAX_ROUNDS = M) - //! \brief The default number of rounds for the algorithm based on key length - //! provided by a static function. - //! \param keylength the size of the key, in bytes - //! \details keylength is unused in the default implementation. + /// \brief The default number of rounds for the algorithm based on key length + /// provided by a static function. + /// \param keylength the size of the key, in bytes + /// \details keylength is unused in the default implementation. CRYPTOPP_STATIC_CONSTEXPR unsigned int StaticGetDefaultRounds(size_t keylength) { return CRYPTOPP_UNUSED(keylength), static_cast(DEFAULT_ROUNDS); } protected: - //! \brief Validates the number of rounds for an algorithm. - //! \param rounds the candidate number of rounds - //! \param alg an Algorithm object used if the number of rounds are invalid - //! \throws InvalidRounds if the number of rounds are invalid - //! \details ThrowIfInvalidRounds() validates the number of rounds and throws if invalid. + /// \brief Validates the number of rounds for an algorithm. + /// \param rounds the candidate number of rounds + /// \param alg an Algorithm object used if the number of rounds are invalid + /// \throws InvalidRounds if the number of rounds are invalid + /// \details ThrowIfInvalidRounds() validates the number of rounds and throws if invalid. inline void ThrowIfInvalidRounds(int rounds, const Algorithm *alg) { if (M == INT_MAX) // Coverity and result_independent_of_operands @@ -124,12 +124,12 @@ protected: } } - //! \brief Validates the number of rounds for an algorithm - //! \param param the candidate number of rounds - //! \param alg an Algorithm object used if the number of rounds are invalid - //! \returns the number of rounds for the algorithm - //! \throws InvalidRounds if the number of rounds are invalid - //! \details GetRoundsAndThrowIfInvalid() validates the number of rounds and throws if invalid. + /// \brief Validates the number of rounds for an algorithm + /// \param param the candidate number of rounds + /// \param alg an Algorithm object used if the number of rounds are invalid + /// \returns the number of rounds for the algorithm + /// \throws InvalidRounds if the number of rounds are invalid + /// \details GetRoundsAndThrowIfInvalid() validates the number of rounds and throws if invalid. inline unsigned int GetRoundsAndThrowIfInvalid(const NameValuePairs ¶m, const Algorithm *alg) { int rounds = param.GetIntValueWithDefault("Rounds", DEFAULT_ROUNDS); @@ -138,45 +138,45 @@ protected: } }; -//! \class VariableBlockSize -//! \brief Inherited by algorithms with variable blocksize -//! \tparam D Default blocksize -//! \tparam N Minimum blocksize -//! \tparam M Maximum blocksize +/// \class VariableBlockSize +/// \brief Inherited by algorithms with variable blocksize +/// \tparam D Default blocksize +/// \tparam N Minimum blocksize +/// \tparam M Maximum blocksize template // use INT_MAX here because enums are treated as signed ints class VariableBlockSize { public: - //! \brief The default blocksize for the algorithm provided as a constant. + /// \brief The default blocksize for the algorithm provided as a constant. CRYPTOPP_CONSTANT(DEFAULT_BLOCKSIZE = D) - //! \brief The minimum blocksize for the algorithm provided as a constant. + /// \brief The minimum blocksize for the algorithm provided as a constant. CRYPTOPP_CONSTANT(MIN_BLOCKSIZE = N) - //! \brief The maximum blocksize for the algorithm provided as a constant. + /// \brief The maximum blocksize for the algorithm provided as a constant. CRYPTOPP_CONSTANT(MAX_BLOCKSIZE = M) - //! \brief The default block size for the algorithm provided by a static function. - //! \param blocksize the block size, in bytes - //! \details The default implementation returns BLOCKSIZE. blocksize is unused - //! in the default implementation. + /// \brief The default block size for the algorithm provided by a static function. + /// \param blocksize the block size, in bytes + /// \details The default implementation returns BLOCKSIZE. blocksize is unused + /// in the default implementation. CRYPTOPP_STATIC_CONSTEXPR size_t CRYPTOPP_API StaticGetValidBlockSize(size_t blocksize) { return CRYPTOPP_UNUSED(blocksize), static_cast(DEFAULT_BLOCKSIZE); } - //! \brief The default block size under a key provided by a static function. - //! \param keylength the size of the key, in bytes - //! \param blocksize the block size, in bytes - //! \details The default implementation returns BLOCKSIZE. blocksize is unused - //! in the default implementation. + /// \brief The default block size under a key provided by a static function. + /// \param keylength the size of the key, in bytes + /// \param blocksize the block size, in bytes + /// \details The default implementation returns BLOCKSIZE. blocksize is unused + /// in the default implementation. CRYPTOPP_STATIC_CONSTEXPR size_t CRYPTOPP_API StaticGetValidBlockSize(size_t keylength, size_t blocksize) { return CRYPTOPP_UNUSED(keylength), CRYPTOPP_UNUSED(blocksize), static_cast(DEFAULT_BLOCKSIZE); } protected: - //! \brief Validates the blocksize for an algorithm. - //! \param blocksize the candidate blocksize - //! \param alg an Algorithm object used if the blocksize is invalid - //! \throws InvalidBlockSize if the blocksize is invalid - //! \details ThrowIfInvalidBlockSize() validates the blocksize and throws if invalid. + /// \brief Validates the blocksize for an algorithm. + /// \param blocksize the candidate blocksize + /// \param alg an Algorithm object used if the blocksize is invalid + /// \throws InvalidBlockSize if the blocksize is invalid + /// \details ThrowIfInvalidBlockSize() validates the blocksize and throws if invalid. inline void ThrowIfInvalidBlockSize(int blocksize, const Algorithm *alg) { if (M == INT_MAX) // Coverity and result_independent_of_operands @@ -191,12 +191,12 @@ protected: } } - //! \brief Validates the blocksize for an algorithm - //! \param param the candidate blocksize - //! \param alg an Algorithm object used if the blocksize is invalid - //! \returns the blocksize for the algorithm - //! \throws InvalidBlockSize if the blocksize is invalid - //! \details GetBlockSizeAndThrowIfInvalid() validates the blocksize and throws if invalid. + /// \brief Validates the blocksize for an algorithm + /// \param param the candidate blocksize + /// \param alg an Algorithm object used if the blocksize is invalid + /// \returns the blocksize for the algorithm + /// \throws InvalidBlockSize if the blocksize is invalid + /// \details GetBlockSizeAndThrowIfInvalid() validates the blocksize and throws if invalid. inline unsigned int GetBlockSizeAndThrowIfInvalid(const NameValuePairs ¶m, const Algorithm *alg) { int keylength = param.GetIntValueWithDefault("KeySize", 0); @@ -208,103 +208,103 @@ protected: return static_cast(blocksize); } - //! Provides the block size of the cipher - //! \return the block size, in bytes - //! \details The sematics of BlockSize() is return DEFAULT_BLOCKSIZE if the default blocksize - //! is in effect. If the blocksize has changed, then the value returned is the BlockSize() - //! parameter used during SetKey(). - //! \details DEFAULT_BLOCKSIZE should be paired with DEFAULT_KEYLENGTH, and it is the same as - //! BLOCKSIZE in a FixedBlockSize cipher. + /// Provides the block size of the cipher + /// \return the block size, in bytes + /// \details The sematics of BlockSize() is return DEFAULT_BLOCKSIZE if the default blocksize + /// is in effect. If the blocksize has changed, then the value returned is the BlockSize() + /// parameter used during SetKey(). + /// \details DEFAULT_BLOCKSIZE should be paired with DEFAULT_KEYLENGTH, and it is the same as + /// BLOCKSIZE in a FixedBlockSize cipher. virtual unsigned int BlockSize() const =0; - //! Provides the minimum block size of the cipher - //! \return the minimum block size, in bytes - //! \details MinBlockSize() returns the smallest blocksize a cipher can use. The size can - //! be affected by the key length. For example, Threefish has key sizes of 256, 512 and 1024 bits, - //! and the blocksize follows the key length. If a 512-bit key is used, then the block size is 512 - //! bits. Once keyed, the minimum block size of 256 is not accurate, nor is a block size of 1024 bit. + /// Provides the minimum block size of the cipher + /// \return the minimum block size, in bytes + /// \details MinBlockSize() returns the smallest blocksize a cipher can use. The size can + /// be affected by the key length. For example, Threefish has key sizes of 256, 512 and 1024 bits, + /// and the blocksize follows the key length. If a 512-bit key is used, then the block size is 512 + /// bits. Once keyed, the minimum block size of 256 is not accurate, nor is a block size of 1024 bit. virtual unsigned int MinBlockSize() const { return MIN_BLOCKSIZE; } - //! Provides the maximum block size of the cipher - //! \return the maximum block size, in bytes - //! \details MaxBlockSize() returns the largest blocksize a cipher can use. The size can - //! be affected by the key length. For example, Threefish has key sizes of 256, 512 and 1024 bits, - //! and the blocksize follows the key length. If a 512-bit key is used, then the block size is 512 - //! bits. Once keyed, the minimum block size of 256 is not accurate, nor is a block size of 1024 bit. + /// Provides the maximum block size of the cipher + /// \return the maximum block size, in bytes + /// \details MaxBlockSize() returns the largest blocksize a cipher can use. The size can + /// be affected by the key length. For example, Threefish has key sizes of 256, 512 and 1024 bits, + /// and the blocksize follows the key length. If a 512-bit key is used, then the block size is 512 + /// bits. Once keyed, the minimum block size of 256 is not accurate, nor is a block size of 1024 bit. virtual unsigned int MaxBlockSize() const { return MAX_BLOCKSIZE; } - //! Provides the initialization vector length of the cipher - //! \return the initialization vector length, in bytes - //! \details The sematics of IVSize() is return IV_LENGTH if the default blocksize is - //! in effect. If the blocksize has changed, then the default implentation returns the value of - //! the BlockSize() parameter used during SetKey(). - //! \details Derived classes may override the behavior such that a different value is returned. - //! This may happen with a cipher that requires an IV that is twice the block size. + /// Provides the initialization vector length of the cipher + /// \return the initialization vector length, in bytes + /// \details The sematics of IVSize() is return IV_LENGTH if the default blocksize is + /// in effect. If the blocksize has changed, then the default implentation returns the value of + /// the BlockSize() parameter used during SetKey(). + /// \details Derived classes may override the behavior such that a different value is returned. + /// This may happen with a cipher that requires an IV that is twice the block size. virtual unsigned int IVSize() const =0; - //! \brief Provides the minimum size of an IV - //! \return minimal length of IVs accepted by this cipher, in bytes + /// \brief Provides the minimum size of an IV + /// \return minimal length of IVs accepted by this cipher, in bytes virtual unsigned int MinIVLength() const { return MIN_BLOCKSIZE; } - //! \brief Provides the maximum size of an IV - //! \return maximal length of IVs accepted by this cipher, in bytes + /// \brief Provides the maximum size of an IV + /// \return maximal length of IVs accepted by this cipher, in bytes virtual unsigned int MaxIVLength() const { return MAX_BLOCKSIZE; } }; // ************** key length *************** -//! \class FixedKeyLength -//! \brief Inherited by keyed algorithms with fixed key length -//! \tparam N Default key length, in bytes -//! \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements" -//! \tparam IV_L default IV length, in bytes -//! \sa SimpleKeyingInterface +/// \class FixedKeyLength +/// \brief Inherited by keyed algorithms with fixed key length +/// \tparam N Default key length, in bytes +/// \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements" +/// \tparam IV_L default IV length, in bytes +/// \sa SimpleKeyingInterface template class FixedKeyLength { public: - //! \brief The default key length used by the algorithm provided as a constant - //! \details KEYLENGTH is provided in bytes, not bits + /// \brief The default key length used by the algorithm provided as a constant + /// \details KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(KEYLENGTH=N) - //! \brief The minimum key length used by the algorithm provided as a constant - //! \details MIN_KEYLENGTH is provided in bytes, not bits + /// \brief The minimum key length used by the algorithm provided as a constant + /// \details MIN_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(MIN_KEYLENGTH=N) - //! \brief The maximum key length used by the algorithm provided as a constant - //! \details MAX_KEYLENGTH is provided in bytes, not bits + /// \brief The maximum key length used by the algorithm provided as a constant + /// \details MAX_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(MAX_KEYLENGTH=N) - //! \brief The default key length used by the algorithm provided as a constant - //! \details DEFAULT_KEYLENGTH is provided in bytes, not bits + /// \brief The default key length used by the algorithm provided as a constant + /// \details DEFAULT_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=N) - //! \brief The default IV requirements for the algorithm provided as a constant - //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement - //! in cryptlib.h for allowed values. + /// \brief The default IV requirements for the algorithm provided as a constant + /// \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement + /// in cryptlib.h for allowed values. CRYPTOPP_CONSTANT(IV_REQUIREMENT = IV_REQ) - //! \brief The default IV length used by the algorithm provided as a constant - //! \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. + /// \brief The default IV length used by the algorithm provided as a constant + /// \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. CRYPTOPP_CONSTANT(IV_LENGTH = IV_L) - //! \brief The default key length for the algorithm provided by a static function. - //! \param keylength the size of the key, in bytes - //! \details The default implementation returns KEYLENGTH. keylength is unused - //! in the default implementation. + /// \brief The default key length for the algorithm provided by a static function. + /// \param keylength the size of the key, in bytes + /// \details The default implementation returns KEYLENGTH. keylength is unused + /// in the default implementation. CRYPTOPP_STATIC_CONSTEXPR size_t CRYPTOPP_API StaticGetValidKeyLength(size_t keylength) { return CRYPTOPP_UNUSED(keylength), static_cast(KEYLENGTH); } }; -//! \class VariableKeyLength -//! \brief Inherited by keyed algorithms with variable key length -//! \tparam D Default key length, in bytes -//! \tparam N Minimum key length, in bytes -//! \tparam M Maximum key length, in bytes -//! \tparam Q Default key length multiple, in bytes. The default multiple is 1. -//! \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements" -//! \tparam IV_L default IV length, in bytes. The default length is 0. -//! \sa SimpleKeyingInterface +/// \class VariableKeyLength +/// \brief Inherited by keyed algorithms with variable key length +/// \tparam D Default key length, in bytes +/// \tparam N Minimum key length, in bytes +/// \tparam M Maximum key length, in bytes +/// \tparam Q Default key length multiple, in bytes. The default multiple is 1. +/// \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements" +/// \tparam IV_L default IV length, in bytes. The default length is 0. +/// \sa SimpleKeyingInterface template class VariableKeyLength { @@ -317,33 +317,33 @@ class VariableKeyLength CRYPTOPP_COMPILE_ASSERT(M >= D); public: - //! \brief The minimum key length used by the algorithm provided as a constant - //! \details MIN_KEYLENGTH is provided in bytes, not bits + /// \brief The minimum key length used by the algorithm provided as a constant + /// \details MIN_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(MIN_KEYLENGTH=N) - //! \brief The maximum key length used by the algorithm provided as a constant - //! \details MAX_KEYLENGTH is provided in bytes, not bits + /// \brief The maximum key length used by the algorithm provided as a constant + /// \details MAX_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(MAX_KEYLENGTH=M) - //! \brief The default key length used by the algorithm provided as a constant - //! \details DEFAULT_KEYLENGTH is provided in bytes, not bits + /// \brief The default key length used by the algorithm provided as a constant + /// \details DEFAULT_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=D) - //! \brief The key length multiple used by the algorithm provided as a constant - //! \details MAX_KEYLENGTH is provided in bytes, not bits + /// \brief The key length multiple used by the algorithm provided as a constant + /// \details MAX_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(KEYLENGTH_MULTIPLE=Q) - //! \brief The default IV requirements for the algorithm provided as a constant - //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement - //! in cryptlib.h for allowed values. + /// \brief The default IV requirements for the algorithm provided as a constant + /// \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement + /// in cryptlib.h for allowed values. CRYPTOPP_CONSTANT(IV_REQUIREMENT=IV_REQ) - //! \brief The default initialization vector length for the algorithm provided as a constant - //! \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. + /// \brief The default initialization vector length for the algorithm provided as a constant + /// \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. CRYPTOPP_CONSTANT(IV_LENGTH=IV_L) - //! \brief Provides a valid key length for the algorithm provided by a static function. - //! \param keylength the size of the key, in bytes - //! \details If keylength is less than MIN_KEYLENGTH, then the function returns - //! MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, then the function - //! returns MAX_KEYLENGTH. If keylength is a multiple of KEYLENGTH_MULTIPLE, - //! then keylength is returned. Otherwise, the function returns keylength rounded - //! \a down to the next smaller multiple of KEYLENGTH_MULTIPLE. - //! \details keylength is provided in bytes, not bits. + /// \brief Provides a valid key length for the algorithm provided by a static function. + /// \param keylength the size of the key, in bytes + /// \details If keylength is less than MIN_KEYLENGTH, then the function returns + /// MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, then the function + /// returns MAX_KEYLENGTH. If keylength is a multiple of KEYLENGTH_MULTIPLE, + /// then keylength is returned. Otherwise, the function returns keylength rounded + /// \a down to the next smaller multiple of KEYLENGTH_MULTIPLE. + /// \details keylength is provided in bytes, not bits. CRYPTOPP_STATIC_CONSTEXPR size_t CRYPTOPP_API StaticGetValidKeyLength(size_t keylength) { return (keylength <= N) ? N : @@ -352,117 +352,117 @@ public: } }; -//! \class SameKeyLengthAs -//! \brief Provides key lengths based on another class's key length -//! \tparam T another FixedKeyLength or VariableKeyLength class -//! \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements" -//! \tparam IV_L default IV length, in bytes -//! \sa SimpleKeyingInterface +/// \class SameKeyLengthAs +/// \brief Provides key lengths based on another class's key length +/// \tparam T another FixedKeyLength or VariableKeyLength class +/// \tparam IV_REQ the \ref SimpleKeyingInterface::IV_Requirement "IV requirements" +/// \tparam IV_L default IV length, in bytes +/// \sa SimpleKeyingInterface template class SameKeyLengthAs { public: - //! \brief The minimum key length used by the algorithm provided as a constant - //! \details MIN_KEYLENGTH is provided in bytes, not bits + /// \brief The minimum key length used by the algorithm provided as a constant + /// \details MIN_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(MIN_KEYLENGTH=T::MIN_KEYLENGTH) - //! \brief The maximum key length used by the algorithm provided as a constant - //! \details MIN_KEYLENGTH is provided in bytes, not bits + /// \brief The maximum key length used by the algorithm provided as a constant + /// \details MIN_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(MAX_KEYLENGTH=T::MAX_KEYLENGTH) - //! \brief The default key length used by the algorithm provided as a constant - //! \details MIN_KEYLENGTH is provided in bytes, not bits + /// \brief The default key length used by the algorithm provided as a constant + /// \details MIN_KEYLENGTH is provided in bytes, not bits CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=T::DEFAULT_KEYLENGTH) - //! \brief The default IV requirements for the algorithm provided as a constant - //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement - //! in cryptlib.h for allowed values. + /// \brief The default IV requirements for the algorithm provided as a constant + /// \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement + /// in cryptlib.h for allowed values. CRYPTOPP_CONSTANT(IV_REQUIREMENT=IV_REQ) - //! \brief The default initialization vector length for the algorithm provided as a constant - //! \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. + /// \brief The default initialization vector length for the algorithm provided as a constant + /// \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. CRYPTOPP_CONSTANT(IV_LENGTH=IV_L) - //! \brief Provides a valid key length for the algorithm provided by a static function. - //! \param keylength the size of the key, in bytes - //! \details If keylength is less than MIN_KEYLENGTH, then the function returns - //! MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, then the function - //! returns MAX_KEYLENGTH. If keylength is a multiple of KEYLENGTH_MULTIPLE, - //! then keylength is returned. Otherwise, the function returns keylength rounded - //! \a down to the next smaller multiple of KEYLENGTH_MULTIPLE. - //! \details keylength is provided in bytes, not bits. + /// \brief Provides a valid key length for the algorithm provided by a static function. + /// \param keylength the size of the key, in bytes + /// \details If keylength is less than MIN_KEYLENGTH, then the function returns + /// MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, then the function + /// returns MAX_KEYLENGTH. If keylength is a multiple of KEYLENGTH_MULTIPLE, + /// then keylength is returned. Otherwise, the function returns keylength rounded + /// \a down to the next smaller multiple of KEYLENGTH_MULTIPLE. + /// \details keylength is provided in bytes, not bits. CRYPTOPP_STATIC_CONSTEXPR size_t CRYPTOPP_API StaticGetValidKeyLength(size_t keylength) {return T::StaticGetValidKeyLength(keylength);} }; // ************** implementation helper for SimpleKeyingInterface *************** -//! \class SimpleKeyingInterfaceImpl -//! \brief Provides a base implementation of SimpleKeyingInterface -//! \tparam BASE a SimpleKeyingInterface derived class -//! \tparam INFO a SimpleKeyingInterface derived class -//! \details SimpleKeyingInterfaceImpl() provides a default implementation for ciphers providing a keying interface. -//! Functions are virtual and not eligible for C++11 constexpr-ness. -//! \sa Algorithm(), SimpleKeyingInterface() +/// \class SimpleKeyingInterfaceImpl +/// \brief Provides a base implementation of SimpleKeyingInterface +/// \tparam BASE a SimpleKeyingInterface derived class +/// \tparam INFO a SimpleKeyingInterface derived class +/// \details SimpleKeyingInterfaceImpl() provides a default implementation for ciphers providing a keying interface. +/// Functions are virtual and not eligible for C++11 constexpr-ness. +/// \sa Algorithm(), SimpleKeyingInterface() template class CRYPTOPP_NO_VTABLE SimpleKeyingInterfaceImpl : public BASE { public: - //! \brief The minimum key length used by the algorithm - //! \returns minimum key length used by the algorithm, in bytes + /// \brief The minimum key length used by the algorithm + /// \returns minimum key length used by the algorithm, in bytes size_t MinKeyLength() const {return INFO::MIN_KEYLENGTH;} - //! \brief The maximum key length used by the algorithm - //! \returns maximum key length used by the algorithm, in bytes + /// \brief The maximum key length used by the algorithm + /// \returns maximum key length used by the algorithm, in bytes size_t MaxKeyLength() const {return (size_t)INFO::MAX_KEYLENGTH;} - //! \brief The default key length used by the algorithm - //! \returns default key length used by the algorithm, in bytes + /// \brief The default key length used by the algorithm + /// \returns default key length used by the algorithm, in bytes size_t DefaultKeyLength() const {return INFO::DEFAULT_KEYLENGTH;} - //! \brief Provides a valid key length for the algorithm - //! \param keylength the size of the key, in bytes - //! \returns the valid key length, in bytes - //! \details keylength is provided in bytes, not bits. If keylength is less than MIN_KEYLENGTH, - //! then the function returns MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, - //! then the function returns MAX_KEYLENGTH. if If keylength is a multiple of KEYLENGTH_MULTIPLE, - //! then keylength is returned. Otherwise, the function returns a \a lower multiple of - //! KEYLENGTH_MULTIPLE. + /// \brief Provides a valid key length for the algorithm + /// \param keylength the size of the key, in bytes + /// \returns the valid key length, in bytes + /// \details keylength is provided in bytes, not bits. If keylength is less than MIN_KEYLENGTH, + /// then the function returns MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, + /// then the function returns MAX_KEYLENGTH. if If keylength is a multiple of KEYLENGTH_MULTIPLE, + /// then keylength is returned. Otherwise, the function returns a \a lower multiple of + /// KEYLENGTH_MULTIPLE. size_t GetValidKeyLength(size_t keylength) const {return INFO::StaticGetValidKeyLength(keylength);} - //! \brief The default IV requirements for the algorithm - //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement - //! in cryptlib.h for allowed values. + /// \brief The default IV requirements for the algorithm + /// \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement + /// in cryptlib.h for allowed values. SimpleKeyingInterface::IV_Requirement IVRequirement() const {return (SimpleKeyingInterface::IV_Requirement)INFO::IV_REQUIREMENT;} - //! \brief The default initialization vector length for the algorithm - //! \details IVSize is provided in bytes, not bits. The default implementation uses IV_LENGTH, which is 0. + /// \brief The default initialization vector length for the algorithm + /// \details IVSize is provided in bytes, not bits. The default implementation uses IV_LENGTH, which is 0. unsigned int IVSize() const {return INFO::IV_LENGTH;} }; -//! \class BlockCipherImpl -//! \brief Provides a base implementation of Algorithm and SimpleKeyingInterface for block ciphers -//! \tparam INFO a SimpleKeyingInterface derived class -//! \tparam BASE a SimpleKeyingInterface derived class -//! \details BlockCipherImpl() provides a default implementation for block ciphers using AlgorithmImpl() -//! and SimpleKeyingInterfaceImpl(). Functions are virtual and not eligible for C++11 constexpr-ness. -//! \sa Algorithm(), SimpleKeyingInterface(), AlgorithmImpl(), SimpleKeyingInterfaceImpl() +/// \class BlockCipherImpl +/// \brief Provides a base implementation of Algorithm and SimpleKeyingInterface for block ciphers +/// \tparam INFO a SimpleKeyingInterface derived class +/// \tparam BASE a SimpleKeyingInterface derived class +/// \details BlockCipherImpl() provides a default implementation for block ciphers using AlgorithmImpl() +/// and SimpleKeyingInterfaceImpl(). Functions are virtual and not eligible for C++11 constexpr-ness. +/// \sa Algorithm(), SimpleKeyingInterface(), AlgorithmImpl(), SimpleKeyingInterfaceImpl() template class CRYPTOPP_NO_VTABLE BlockCipherImpl : public AlgorithmImpl > > { public: - //! Provides the block size of the algorithm - //! \returns the block size of the algorithm, in bytes + /// Provides the block size of the algorithm + /// \returns the block size of the algorithm, in bytes unsigned int BlockSize() const {return this->BLOCKSIZE;} }; -//! \class VariableBlockCipherImpl -//! \brief Provides a base implementation of Algorithm and SimpleKeyingInterface for block ciphers with varibale block sizes -//! \tparam INFO a SimpleKeyingInterface derived class -//! \tparam BASE a SimpleKeyingInterface derived class -//! \details VariableBlockCipherImpl() provides a default implementation for block ciphers with varibale block sizes using AlgorithmImpl() -//! and SimpleKeyingInterfaceImpl(). -//! \sa Algorithm(), SimpleKeyingInterface(), AlgorithmImpl(), SimpleKeyingInterfaceImpl() +/// \class VariableBlockCipherImpl +/// \brief Provides a base implementation of Algorithm and SimpleKeyingInterface for block ciphers with varibale block sizes +/// \tparam INFO a SimpleKeyingInterface derived class +/// \tparam BASE a SimpleKeyingInterface derived class +/// \details VariableBlockCipherImpl() provides a default implementation for block ciphers with varibale block sizes using AlgorithmImpl() +/// and SimpleKeyingInterfaceImpl(). +/// \sa Algorithm(), SimpleKeyingInterface(), AlgorithmImpl(), SimpleKeyingInterfaceImpl() template class CRYPTOPP_NO_VTABLE VariableBlockCipherImpl : public AlgorithmImpl > > { @@ -471,15 +471,15 @@ public: VariableBlockCipherImpl(unsigned int blockSize) : m_blocksize(blockSize), m_ivlength(blockSize) {} VariableBlockCipherImpl(unsigned int blockSize, unsigned int ivLength) : m_blocksize(blockSize), m_ivlength(ivLength) {} - //! Provides the block size of the algorithm - //! \returns the block size, in bytes + /// Provides the block size of the algorithm + /// \returns the block size, in bytes unsigned int BlockSize() const { return m_blocksize ? m_blocksize : static_cast(this->DEFAULT_BLOCKSIZE); } - //! Provides the initialization vector length of the algorithm - //! \returns the initialization vector length, in bytes + /// Provides the initialization vector length of the algorithm + /// \returns the initialization vector length, in bytes unsigned int IVSize() const { if (!this->IsResynchronizable()) throw NotImplemented(this->GetAlgorithm().AlgorithmName() + ": this object doesn't support resynchronization"); @@ -491,129 +491,129 @@ protected: unsigned int m_blocksize, m_ivlength; }; -//! \class BlockCipherFinal -//! \brief Provides class member functions to key a block cipher -//! \tparam DIR a CipherDir -//! \tparam BASE a BlockCipherImpl derived class +/// \class BlockCipherFinal +/// \brief Provides class member functions to key a block cipher +/// \tparam DIR a CipherDir +/// \tparam BASE a BlockCipherImpl derived class template class BlockCipherFinal : public ClonableImpl, BASE> { public: - //! \brief Construct a default BlockCipherFinal - //! \details The cipher is not keyed. + /// \brief Construct a default BlockCipherFinal + /// \details The cipher is not keyed. BlockCipherFinal() {} - //! \brief Construct a BlockCipherFinal - //! \param key a byte array used to key the cipher - //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls - //! SimpleKeyingInterface::SetKey. + /// \brief Construct a BlockCipherFinal + /// \param key a byte array used to key the cipher + /// \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls + /// SimpleKeyingInterface::SetKey. BlockCipherFinal(const byte *key) {this->SetKey(key, this->DEFAULT_KEYLENGTH);} - //! \brief Construct a BlockCipherFinal - //! \param key a byte array used to key the cipher - //! \param length the length of the byte array - //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls - //! SimpleKeyingInterface::SetKey. + /// \brief Construct a BlockCipherFinal + /// \param key a byte array used to key the cipher + /// \param length the length of the byte array + /// \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls + /// SimpleKeyingInterface::SetKey. BlockCipherFinal(const byte *key, size_t length) {this->SetKey(key, length);} - //! \brief Construct a BlockCipherFinal - //! \param key a byte array used to key the cipher - //! \param length the length of the byte array - //! \param rounds the number of rounds - //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls - //! SimpleKeyingInterface::SetKeyWithRounds. + /// \brief Construct a BlockCipherFinal + /// \param key a byte array used to key the cipher + /// \param length the length of the byte array + /// \param rounds the number of rounds + /// \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls + /// SimpleKeyingInterface::SetKeyWithRounds. BlockCipherFinal(const byte *key, size_t length, unsigned int rounds) {this->SetKeyWithRounds(key, length, rounds);} - //! \brief Provides the direction of the cipher - //! \returns true if DIR is ENCRYPTION, false otherwise - //! \sa GetCipherDirection(), IsPermutation() + /// \brief Provides the direction of the cipher + /// \returns true if DIR is ENCRYPTION, false otherwise + /// \sa GetCipherDirection(), IsPermutation() bool IsForwardTransformation() const {return DIR == ENCRYPTION;} }; -//! \class MessageAuthenticationCodeImpl -//! \brief Provides a base implementation of Algorithm and SimpleKeyingInterface for message authentication codes -//! \tparam INFO a SimpleKeyingInterface derived class -//! \tparam BASE a SimpleKeyingInterface derived class -//! \details MessageAuthenticationCodeImpl() provides a default implementation for message authentication codes -//! using AlgorithmImpl() and SimpleKeyingInterfaceImpl(). Functions are virtual and not subject to C++11 -//! constexpr. -//! \sa Algorithm(), SimpleKeyingInterface(), AlgorithmImpl(), SimpleKeyingInterfaceImpl() +/// \class MessageAuthenticationCodeImpl +/// \brief Provides a base implementation of Algorithm and SimpleKeyingInterface for message authentication codes +/// \tparam INFO a SimpleKeyingInterface derived class +/// \tparam BASE a SimpleKeyingInterface derived class +/// \details MessageAuthenticationCodeImpl() provides a default implementation for message authentication codes +/// using AlgorithmImpl() and SimpleKeyingInterfaceImpl(). Functions are virtual and not subject to C++11 +/// constexpr. +/// \sa Algorithm(), SimpleKeyingInterface(), AlgorithmImpl(), SimpleKeyingInterfaceImpl() template class MessageAuthenticationCodeImpl : public AlgorithmImpl, INFO> { }; -//! \class MessageAuthenticationCodeFinal -//! \brief Provides class member functions to key a message authentication code -//! \tparam BASE a BlockCipherImpl derived class -//! \details A default implementation for MessageAuthenticationCode +/// \class MessageAuthenticationCodeFinal +/// \brief Provides class member functions to key a message authentication code +/// \tparam BASE a BlockCipherImpl derived class +/// \details A default implementation for MessageAuthenticationCode template class MessageAuthenticationCodeFinal : public ClonableImpl, MessageAuthenticationCodeImpl > { public: - //! \brief Construct a default MessageAuthenticationCodeFinal - //! \details The message authentication code is not keyed. + /// \brief Construct a default MessageAuthenticationCodeFinal + /// \details The message authentication code is not keyed. MessageAuthenticationCodeFinal() {} - //! \brief Construct a BlockCipherFinal - //! \param key a byte array used to key the algorithm - //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls - //! SimpleKeyingInterface::SetKey. + /// \brief Construct a BlockCipherFinal + /// \param key a byte array used to key the algorithm + /// \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls + /// SimpleKeyingInterface::SetKey. MessageAuthenticationCodeFinal(const byte *key) {this->SetKey(key, this->DEFAULT_KEYLENGTH);} - //! \brief Construct a BlockCipherFinal - //! \param key a byte array used to key the algorithm - //! \param length the length of the byte array - //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls - //! SimpleKeyingInterface::SetKey. + /// \brief Construct a BlockCipherFinal + /// \param key a byte array used to key the algorithm + /// \param length the length of the byte array + /// \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls + /// SimpleKeyingInterface::SetKey. MessageAuthenticationCodeFinal(const byte *key, size_t length) {this->SetKey(key, length);} }; // ************** documentation *************** -//! \class BlockCipherDocumentation -//! \brief Provides Encryption and Decryption typedefs used by derived classes to -//! implement a block cipher -//! \details These objects usually should not be used directly. See CipherModeDocumentation -//! instead. Each class derived from this one defines two types, Encryption and Decryption, -//! both of which implement the BlockCipher interface. +/// \class BlockCipherDocumentation +/// \brief Provides Encryption and Decryption typedefs used by derived classes to +/// implement a block cipher +/// \details These objects usually should not be used directly. See CipherModeDocumentation +/// instead. Each class derived from this one defines two types, Encryption and Decryption, +/// both of which implement the BlockCipher interface. struct BlockCipherDocumentation { - //! implements the BlockCipher interface + /// implements the BlockCipher interface typedef BlockCipher Encryption; - //! implements the BlockCipher interface + /// implements the BlockCipher interface typedef BlockCipher Decryption; }; -//! \class SymmetricCipherDocumentation -//! \brief Provides Encryption and Decryption typedefs used by derived classes to -//! implement a symmetric cipher -//! \details Each class derived from this one defines two types, Encryption and Decryption, -//! both of which implement the SymmetricCipher interface. Two types of classes derive -//! from this class: stream ciphers and block cipher modes. Stream ciphers can be used -//! alone, cipher mode classes need to be used with a block cipher. See CipherModeDocumentation -//! for more for information about using cipher modes and block ciphers. +/// \class SymmetricCipherDocumentation +/// \brief Provides Encryption and Decryption typedefs used by derived classes to +/// implement a symmetric cipher +/// \details Each class derived from this one defines two types, Encryption and Decryption, +/// both of which implement the SymmetricCipher interface. Two types of classes derive +/// from this class: stream ciphers and block cipher modes. Stream ciphers can be used +/// alone, cipher mode classes need to be used with a block cipher. See CipherModeDocumentation +/// for more for information about using cipher modes and block ciphers. struct SymmetricCipherDocumentation { - //! implements the SymmetricCipher interface + /// implements the SymmetricCipher interface typedef SymmetricCipher Encryption; - //! implements the SymmetricCipher interface + /// implements the SymmetricCipher interface typedef SymmetricCipher Decryption; }; -//! \class AuthenticatedSymmetricCipherDocumentation -//! \brief Provides Encryption and Decryption typedefs used by derived classes to -//! implement an authenticated encryption cipher -//! \details Each class derived from this one defines two types, Encryption and Decryption, -//! both of which implement the AuthenticatedSymmetricCipher interface. +/// \class AuthenticatedSymmetricCipherDocumentation +/// \brief Provides Encryption and Decryption typedefs used by derived classes to +/// implement an authenticated encryption cipher +/// \details Each class derived from this one defines two types, Encryption and Decryption, +/// both of which implement the AuthenticatedSymmetricCipher interface. struct AuthenticatedSymmetricCipherDocumentation { - //! implements the AuthenticatedSymmetricCipher interface + /// implements the AuthenticatedSymmetricCipher interface typedef AuthenticatedSymmetricCipher Encryption; - //! implements the AuthenticatedSymmetricCipher interface + /// implements the AuthenticatedSymmetricCipher interface typedef AuthenticatedSymmetricCipher Decryption; }; diff --git a/seed.h b/seed.h index 554db308..4231b105 100644 --- a/seed.h +++ b/seed.h @@ -1,8 +1,8 @@ // seed.h - originally written and placed in the public domain by Wei Dai -//! \file seed.h -//! \brief Classes for the SEED block cipher -//! \since Crypto++ 5.6.0 +/// \file seed.h +/// \brief Classes for the SEED block cipher +/// \since Crypto++ 5.6.0 #ifndef CRYPTOPP_SEED_H #define CRYPTOPP_SEED_H @@ -12,18 +12,18 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SEED_Info -//! \brief SEED block cipher information -//! \since Crypto++ 5.6.0 +/// \class SEED_Info +/// \brief SEED block cipher information +/// \since Crypto++ 5.6.0 struct SEED_Info : public FixedBlockSize<16>, public FixedKeyLength<16>, public FixedRounds<16> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "SEED";} }; -//! \class SEED -//! \brief SEED block cipher -//! \sa SEED -//! \since Crypto++ 5.6.0 +/// \class SEED +/// \brief SEED block cipher +/// \sa SEED +/// \since Crypto++ 5.6.0 class SEED : public SEED_Info, public BlockCipherDocumentation { class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl diff --git a/serpent.h b/serpent.h index 65f014d6..277887f3 100644 --- a/serpent.h +++ b/serpent.h @@ -1,7 +1,7 @@ // serpent.h - originally written and placed in the public domain by Wei Dai -//! \file serpent.h -//! \brief Classes for the Serpent block cipher +/// \file serpent.h +/// \brief Classes for the Serpent block cipher #ifndef CRYPTOPP_SERPENT_H #define CRYPTOPP_SERPENT_H @@ -11,15 +11,15 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Serpent_Info -//! \brief Serpent block cipher information +/// \class Serpent_Info +/// \brief Serpent block cipher information struct Serpent_Info : public FixedBlockSize<16>, public VariableKeyLength<16, 16, 32, 8>, public FixedRounds<32> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "Serpent";} }; -//! \class Serpent -//! \brief Serpent block cipher +/// \class Serpent +/// \brief Serpent block cipher /// \sa Serpent class Serpent : public Serpent_Info, public BlockCipherDocumentation { diff --git a/sha.h b/sha.h index c53213a5..06563002 100644 --- a/sha.h +++ b/sha.h @@ -1,9 +1,9 @@ // sha.h - originally written and placed in the public domain by Wei Dai -//! \file sha.h -//! \brief Classes for SHA-1 and SHA-2 family of message digests -//! \since SHA1 since Crypto++ 1.0, SHA2 since Crypto++ 4.0, -//! ARM SHA since Crypto++ 6.0, Intel SHA since Crypto++ 6.0 +/// \file sha.h +/// \brief Classes for SHA-1 and SHA-2 family of message digests +/// \since SHA1 since Crypto++ 1.0, SHA2 since Crypto++ 4.0, +/// ARM SHA since Crypto++ 6.0, Intel SHA since Crypto++ 6.0 #ifndef CRYPTOPP_SHA_H #define CRYPTOPP_SHA_H @@ -19,177 +19,177 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SHA1 -//! \brief SHA-1 message digest -//! \sa SHA-1 -//! \since Crypto++ 1.0, Intel SHA extensions since Crypto++ 6.0 +/// \class SHA1 +/// \brief SHA-1 message digest +/// \sa SHA-1 +/// \since Crypto++ 1.0, Intel SHA extensions since Crypto++ 6.0 class CRYPTOPP_DLL SHA1 : public IteratedHashWithStaticTransform { public: - //! \brief Initialize state array - //! \param state the state of the hash - //! \details InitState sets a state array to SHA1 initial values - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array must be 16-byte aligned for SSE2. + /// \brief Initialize state array + /// \param state the state of the hash + /// \details InitState sets a state array to SHA1 initial values + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array must be 16-byte aligned for SSE2. static void CRYPTOPP_API InitState(HashWordType *state); - //! \brief Operate the hash - //! \param digest the state of the hash - //! \param data the data to be digested - //! \details Transform operates the hash on data. When the call is invoked - //! digest holds initial state. Upon return digest holds the hash - //! or updated state. - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. + /// \brief Operate the hash + /// \param digest the state of the hash + /// \param data the data to be digested + /// \details Transform operates the hash on data. When the call is invoked + /// digest holds initial state. Upon return digest holds the hash + /// or updated state. + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. static void CRYPTOPP_API Transform(HashWordType *digest, const HashWordType *data); - //! \brief The algorithm name - //! \returns C-style string "SHA-1" + /// \brief The algorithm name + /// \returns C-style string "SHA-1" CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "SHA-1";} protected: size_t HashMultipleBlocks(const HashWordType *input, size_t length); }; -//! \class SHA256 -//! \brief SHA-256 message digest -//! \sa SHA-256 -//! \since Crypto++ 4.0, Intel SHA extensions since Crypto++ 6.0 +/// \class SHA256 +/// \brief SHA-256 message digest +/// \sa SHA-256 +/// \since Crypto++ 4.0, Intel SHA extensions since Crypto++ 6.0 class CRYPTOPP_DLL SHA256 : public IteratedHashWithStaticTransform { public: - //! \brief Initialize state array - //! \param state the state of the hash - //! \details InitState sets a state array to SHA256 initial values - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array must be 16-byte aligned for SSE2. + /// \brief Initialize state array + /// \param state the state of the hash + /// \details InitState sets a state array to SHA256 initial values + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array must be 16-byte aligned for SSE2. static void CRYPTOPP_API InitState(HashWordType *state); - //! \brief Operate the hash - //! \param digest the state of the hash - //! \param data the data to be digested - //! \details Transform operates the hash on data. When the call is invoked - //! digest holds initial state. Upon return digest holds the hash - //! or updated state. - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. + /// \brief Operate the hash + /// \param digest the state of the hash + /// \param data the data to be digested + /// \details Transform operates the hash on data. When the call is invoked + /// digest holds initial state. Upon return digest holds the hash + /// or updated state. + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. static void CRYPTOPP_API Transform(HashWordType *digest, const HashWordType *data); - //! \brief The algorithm name - //! \returns C-style string "SHA-256" + /// \brief The algorithm name + /// \returns C-style string "SHA-256" CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "SHA-256";} protected: size_t HashMultipleBlocks(const HashWordType *input, size_t length); }; -//! \class SHA224 -//! \brief SHA-224 message digest -//! \sa SHA-224 -//! \since Crypto++ 4.0, Intel SHA extensions since Crypto++ 6.0 +/// \class SHA224 +/// \brief SHA-224 message digest +/// \sa SHA-224 +/// \since Crypto++ 4.0, Intel SHA extensions since Crypto++ 6.0 class CRYPTOPP_DLL SHA224 : public IteratedHashWithStaticTransform { public: - //! \brief Initialize state array - //! \param state the state of the hash - //! \details InitState sets a state array to SHA224 initial values - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array must be 16-byte aligned for SSE2. + /// \brief Initialize state array + /// \param state the state of the hash + /// \details InitState sets a state array to SHA224 initial values + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array must be 16-byte aligned for SSE2. static void CRYPTOPP_API InitState(HashWordType *state); - //! \brief Operate the hash - //! \param digest the state of the hash - //! \param data the data to be digested - //! \details Transform operates the hash on data. When the call is invoked - //! digest holds initial state. Upon return digest holds the hash - //! or updated state. - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. + /// \brief Operate the hash + /// \param digest the state of the hash + /// \param data the data to be digested + /// \details Transform operates the hash on data. When the call is invoked + /// digest holds initial state. Upon return digest holds the hash + /// or updated state. + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. static void CRYPTOPP_API Transform(HashWordType *digest, const HashWordType *data) {SHA256::Transform(digest, data);} - //! \brief The algorithm name - //! \returns C-style string "SHA-224" + /// \brief The algorithm name + /// \returns C-style string "SHA-224" CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "SHA-224";} protected: size_t HashMultipleBlocks(const HashWordType *input, size_t length); }; -//! \class SHA512 -//! \brief SHA-512 message digest -//! \sa SHA-512 -//! \since Crypto++ 4.0 +/// \class SHA512 +/// \brief SHA-512 message digest +/// \sa SHA-512 +/// \since Crypto++ 4.0 class CRYPTOPP_DLL SHA512 : public IteratedHashWithStaticTransform { public: - //! \brief Initialize state array - //! \param state the state of the hash - //! \details InitState sets a state array to SHA512 initial values - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array must be 16-byte aligned for SSE2. + /// \brief Initialize state array + /// \param state the state of the hash + /// \details InitState sets a state array to SHA512 initial values + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array must be 16-byte aligned for SSE2. static void CRYPTOPP_API InitState(HashWordType *state); - //! \brief Operate the hash - //! \param digest the state of the hash - //! \param data the data to be digested - //! \details Transform operates the hash on data. When the call is invoked - //! digest holds initial state. Upon return digest holds the hash - //! or updated state. - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. + /// \brief Operate the hash + /// \param digest the state of the hash + /// \param data the data to be digested + /// \details Transform operates the hash on data. When the call is invoked + /// digest holds initial state. Upon return digest holds the hash + /// or updated state. + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. static void CRYPTOPP_API Transform(HashWordType *digest, const HashWordType *data); - //! \brief The algorithm name - //! \returns C-style string "SHA-512" + /// \brief The algorithm name + /// \returns C-style string "SHA-512" CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "SHA-512";} }; -//! \class SHA384 -//! \brief SHA-384 message digest -//! \sa SHA-384 -//! \since Crypto++ 4.0 +/// \class SHA384 +/// \brief SHA-384 message digest +/// \sa SHA-384 +/// \since Crypto++ 4.0 class CRYPTOPP_DLL SHA384 : public IteratedHashWithStaticTransform { public: - //! \brief Initialize state array - //! \param state the state of the hash - //! \details InitState sets a state array to SHA384 initial values - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array must be 16-byte aligned for SSE2. + /// \brief Initialize state array + /// \param state the state of the hash + /// \details InitState sets a state array to SHA384 initial values + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array must be 16-byte aligned for SSE2. static void CRYPTOPP_API InitState(HashWordType *state); - //! \brief Operate the hash - //! \param digest the state of the hash - //! \param data the data to be digested - //! \details Transform operates the hash on data. When the call is invoked - //! digest holds initial state. Upon return digest holds the hash - //! or updated state. - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState and Transform. External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. - //! \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. + /// \brief Operate the hash + /// \param digest the state of the hash + /// \param data the data to be digested + /// \details Transform operates the hash on data. When the call is invoked + /// digest holds initial state. Upon return digest holds the hash + /// or updated state. + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState and Transform. External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. + /// \note On Intel platforms the state array and data must be 16-byte aligned for SSE2. static void CRYPTOPP_API Transform(HashWordType *digest, const HashWordType *data) {SHA512::Transform(digest, data);} - //! \brief The algorithm name - //! \returns C-style string "SHA-384" + /// \brief The algorithm name + /// \returns C-style string "SHA-384" CRYPTOPP_STATIC_CONSTEXPR const char* CRYPTOPP_API StaticAlgorithmName() {return "SHA-384";} }; diff --git a/sha3.h b/sha3.h index 3240f591..86fe9758 100644 --- a/sha3.h +++ b/sha3.h @@ -1,12 +1,12 @@ // sha3.h - originally written and placed in the public domain by Wei Dai -//! \file sha3.h -//! \brief Classes for SHA3 message digests -//! \details The Crypto++ implementation conforms to the FIPS 202 version of SHA3 using F1600 with XOF d=0x06. -//! Previous behavior (XOF d=0x01) is available in Keccak classes. -//! \sa SHA-3, -//! SHA-3 STANDARD (FIPS 202). -//! \since Crypto++ 5.6.2 +/// \file sha3.h +/// \brief Classes for SHA3 message digests +/// \details The Crypto++ implementation conforms to the FIPS 202 version of SHA3 using F1600 with XOF d=0x06. +/// Previous behavior (XOF d=0x01) is available in Keccak classes. +/// \sa SHA-3, +/// SHA-3 STANDARD (FIPS 202). +/// \since Crypto++ 5.6.2 #ifndef CRYPTOPP_SHA3_H #define CRYPTOPP_SHA3_H @@ -16,23 +16,23 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SHA3 -//! \brief SHA3 message digest base class -//! \details The Crypto++ implementation conforms to FIPS 202 version of SHA3 using F1600 with XOF d=0x06. -//! Previous behavior (XOF d=0x01) is available in Keccak classes. -//! \details SHA3 is the base class for SHA3_224, SHA3_256, SHA3_384 and SHA3_512. -//! Library users should instantiate a derived class, and only use SHA3 -//! as a base class reference or pointer. -//! \sa Keccak, SHA3_224, SHA3_256, SHA3_384 and SHA3_512. -//! \since Crypto++ 5.6.2 +/// \class SHA3 +/// \brief SHA3 message digest base class +/// \details The Crypto++ implementation conforms to FIPS 202 version of SHA3 using F1600 with XOF d=0x06. +/// Previous behavior (XOF d=0x01) is available in Keccak classes. +/// \details SHA3 is the base class for SHA3_224, SHA3_256, SHA3_384 and SHA3_512. +/// Library users should instantiate a derived class, and only use SHA3 +/// as a base class reference or pointer. +/// \sa Keccak, SHA3_224, SHA3_256, SHA3_384 and SHA3_512. +/// \since Crypto++ 5.6.2 class SHA3 : public HashTransformation { public: - //! \brief Construct a SHA3 - //! \param digestSize the digest size, in bytes - //! \details SHA3 is the base class for SHA3_224, SHA3_256, SHA3_384 and SHA3_512. - //! Library users should instantiate a derived class, and only use SHA3 - //! as a base class reference or pointer. + /// \brief Construct a SHA3 + /// \param digestSize the digest size, in bytes + /// \details SHA3 is the base class for SHA3_224, SHA3_256, SHA3_384 and SHA3_512. + /// Library users should instantiate a derived class, and only use SHA3 + /// as a base class reference or pointer. SHA3(unsigned int digestSize) : m_digestSize(digestSize) {Restart();} unsigned int DigestSize() const {return m_digestSize;} std::string AlgorithmName() const {return "SHA3-" + IntToString(m_digestSize*8);} @@ -51,10 +51,10 @@ protected: unsigned int m_digestSize, m_counter; }; -//! \class SHA3_224 -//! \brief SHA3 message digest template -//! \tparam T_DigestSize the size of the digest, in bytes -//! \since Crypto++ 5.6.2 +/// \class SHA3_224 +/// \brief SHA3 message digest template +/// \tparam T_DigestSize the size of the digest, in bytes +/// \since Crypto++ 5.6.2 template class SHA3_Final : public SHA3 { @@ -62,7 +62,7 @@ public: CRYPTOPP_CONSTANT(DIGESTSIZE = T_DigestSize) CRYPTOPP_CONSTANT(BLOCKSIZE = 200 - 2 * DIGESTSIZE) - //! \brief Construct a SHA3-X message digest + /// \brief Construct a SHA3-X message digest SHA3_Final() : SHA3(DIGESTSIZE) {} static std::string StaticAlgorithmName() { return "SHA3-" + IntToString(DIGESTSIZE * 8); } unsigned int BlockSize() const { return BLOCKSIZE; } @@ -73,29 +73,29 @@ private: #endif }; -//! \brief SHA3-224 message digest -//! \since Crypto++ 5.6.2 +/// \brief SHA3-224 message digest +/// \since Crypto++ 5.6.2 // typedef SHA3_Final<28> SHA3_224; class SHA3_224 : public SHA3_Final<28> { }; -//! \brief SHA3-256 message digest -//! \since Crypto++ 5.6.2 +/// \brief SHA3-256 message digest +/// \since Crypto++ 5.6.2 // typedef SHA3_Final<32> SHA3_256; class SHA3_256 : public SHA3_Final<32> { }; -//! \brief SHA3-384 message digest -//! \since Crypto++ 5.6.2 +/// \brief SHA3-384 message digest +/// \since Crypto++ 5.6.2 // typedef SHA3_Final<48> SHA3_384; class SHA3_384 : public SHA3_Final<48> { }; -//! \brief SHA3-512 message digest -//! \since Crypto++ 5.6.2 +/// \brief SHA3-512 message digest +/// \since Crypto++ 5.6.2 // typedef SHA3_Final<64> SHA3_512; class SHA3_512 : public SHA3_Final<64> { diff --git a/shacal2.h b/shacal2.h index 74af96e7..f2d6adb0 100644 --- a/shacal2.h +++ b/shacal2.h @@ -1,8 +1,8 @@ // shacal.h - originally written and placed in the public domain by Wei Dai -//! \file shacal2.h -//! \brief Classes for the SHACAL-2 block cipher -//! \since Crypto++ 5.2, Intel SHA since Crypto++ 6.0 +/// \file shacal2.h +/// \brief Classes for the SHACAL-2 block cipher +/// \since Crypto++ 5.2, Intel SHA since Crypto++ 6.0 #ifndef CRYPTOPP_SHACAL2_H #define CRYPTOPP_SHACAL2_H @@ -12,21 +12,21 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SHACAL2_Info -//! \brief SHACAL2 block cipher information +/// \class SHACAL2_Info +/// \brief SHACAL2 block cipher information struct SHACAL2_Info : public FixedBlockSize<32>, public VariableKeyLength<16, 16, 64> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "SHACAL-2";} }; -//! \class SHACAL2 -//! \brief SHACAL2 block cipher -//! \since Crypto++ 5.2, Intel SHA since Crypto++ 6.0 -//! \sa SHACAL-2 +/// \class SHACAL2 +/// \brief SHACAL2 block cipher +/// \since Crypto++ 5.2, Intel SHA since Crypto++ 6.0 +/// \sa SHACAL-2 class SHACAL2 : public SHACAL2_Info, public BlockCipherDocumentation { - //! \brief SHACAL2 block cipher transformation functions - //! \details Provides implementation common to encryption and decryption + /// \brief SHACAL2 block cipher transformation functions + /// \details Provides implementation common to encryption and decryption class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -38,16 +38,16 @@ class SHACAL2 : public SHACAL2_Info, public BlockCipherDocumentation static const word32 K[64]; }; - //! \brief SHACAL2 block cipher transformation functions - //! \details Provides implementation for encryption transformation + /// \brief SHACAL2 block cipher transformation functions + /// \details Provides implementation for encryption transformation class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \brief SHACAL2 block cipher transformation functions - //! \details Provides implementation for decryption transformation + /// \brief SHACAL2 block cipher transformation functions + /// \details Provides implementation for decryption transformation class CRYPTOPP_NO_VTABLE Dec : public Base { public: diff --git a/shark.h b/shark.h index d2852827..a39c47a0 100644 --- a/shark.h +++ b/shark.h @@ -1,7 +1,7 @@ // shark.h - originally written and placed in the public domain by Wei Dai -//! \file shark.h -//! \brief Classes for the SHARK block cipher +/// \file shark.h +/// \brief Classes for the SHARK block cipher #ifndef CRYPTOPP_SHARK_H #define CRYPTOPP_SHARK_H @@ -12,20 +12,20 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SHARK_Info -//! \brief SHARK block cipher information +/// \class SHARK_Info +/// \brief SHARK block cipher information struct SHARK_Info : public FixedBlockSize<8>, public FixedKeyLength<16>, public VariableRounds<6, 2> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "SHARK-E";} }; -//! \class SHARK -//! \brief SHARK block cipher +/// \class SHARK +/// \brief SHARK block cipher /// SHARK-E class SHARK : public SHARK_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief SHARK block cipher default operation + /// \class Base + /// \brief SHARK block cipher default operation class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -36,8 +36,8 @@ class SHARK : public SHARK_Info, public BlockCipherDocumentation SecBlock m_roundKeys; }; - //! \class Enc - //! \brief SHARK block cipher encryption operation + /// \class Enc + /// \brief SHARK block cipher encryption operation class CRYPTOPP_NO_VTABLE Enc : public Base { public: @@ -51,8 +51,8 @@ class SHARK : public SHARK_Info, public BlockCipherDocumentation static const word64 cbox[8][256]; }; - //! \class Dec - //! \brief SHARK block cipher decryption operation + /// \class Dec + /// \brief SHARK block cipher decryption operation class CRYPTOPP_NO_VTABLE Dec : public Base { public: diff --git a/simon.cpp b/simon.cpp index c7954309..565a5205 100644 --- a/simon.cpp +++ b/simon.cpp @@ -25,21 +25,21 @@ using CryptoPP::word64; using CryptoPP::rotlConstant; using CryptoPP::rotrConstant; -//! \brief Round transformation helper -//! \tparam W word type -//! \param v value +/// \brief Round transformation helper +/// \tparam W word type +/// \param v value template inline W f(const W v) { return (rotlConstant<1>(v) & rotlConstant<8>(v)) ^ rotlConstant<2>(v); } -//! \brief Round transformation -//! \tparam W word type -//! \param x value -//! \param y value -//! \param k value -//! \param l value +/// \brief Round transformation +/// \tparam W word type +/// \param x value +/// \param y value +/// \param k value +/// \param l value template inline void R2(W& x, W& y, const W k, const W l) { @@ -47,12 +47,12 @@ inline void R2(W& x, W& y, const W k, const W l) x ^= f(y); x ^= l; } -//! \brief Forward transformation -//! \tparam W word type -//! \tparam R number of rounds -//! \param c output array -//! \param p input array -//! \param k subkey array +/// \brief Forward transformation +/// \tparam W word type +/// \tparam R number of rounds +/// \param c output array +/// \param p input array +/// \param k subkey array template inline void SIMON_Encrypt(W c[2], const W p[2], const W k[R]) { @@ -68,12 +68,12 @@ inline void SIMON_Encrypt(W c[2], const W p[2], const W k[R]) } } -//! \brief Reverse transformation -//! \tparam W word type -//! \tparam R number of rounds -//! \param p output array -//! \param c input array -//! \param k subkey array +/// \brief Reverse transformation +/// \tparam W word type +/// \tparam R number of rounds +/// \param p output array +/// \param c input array +/// \param k subkey array template inline void SIMON_Decrypt(W p[2], const W c[2], const W k[R]) { @@ -91,11 +91,11 @@ inline void SIMON_Decrypt(W p[2], const W c[2], const W k[R]) R2(p[1], p[0], k[i + 1], k[i]); } -//! \brief Subkey generation function -//! \details Used for SIMON-64 with 96-bit key and 42 rounds. A template was -//! not worthwhile because all instantiations would need specialization. -//! \param key empty subkey array -//! \param k user key array +/// \brief Subkey generation function +/// \details Used for SIMON-64 with 96-bit key and 42 rounds. A template was +/// not worthwhile because all instantiations would need specialization. +/// \param key empty subkey array +/// \param k user key array inline void SIMON64_ExpandKey_42R3K(word32 key[42], const word32 k[3]) { const word32 c = 0xfffffffc; @@ -109,11 +109,11 @@ inline void SIMON64_ExpandKey_42R3K(word32 key[42], const word32 k[3]) } } -//! \brief Subkey generation function -//! \details Used for SIMON-64 with 128-bit key and 44 rounds. A template was -//! not worthwhile because all instantiations would need specialization. -//! \param key empty subkey array -//! \param k user key array +/// \brief Subkey generation function +/// \details Used for SIMON-64 with 128-bit key and 44 rounds. A template was +/// not worthwhile because all instantiations would need specialization. +/// \param key empty subkey array +/// \param k user key array inline void SIMON64_ExpandKey_44R4K(word32 key[44], const word32 k[4]) { const word32 c = 0xfffffffc; @@ -127,11 +127,11 @@ inline void SIMON64_ExpandKey_44R4K(word32 key[44], const word32 k[4]) } } -//! \brief Subkey generation function -//! \details Used for SIMON-128 with 128-bit key and 68 rounds. A template was -//! not worthwhile because all instantiations would need specialization. -//! \param key empty subkey array -//! \param k user key array +/// \brief Subkey generation function +/// \details Used for SIMON-128 with 128-bit key and 68 rounds. A template was +/// not worthwhile because all instantiations would need specialization. +/// \param key empty subkey array +/// \param k user key array inline void SIMON128_ExpandKey_68R2K(word64 key[68], const word64 k[2]) { const word64 c = W64LIT(0xfffffffffffffffc); @@ -148,11 +148,11 @@ inline void SIMON128_ExpandKey_68R2K(word64 key[68], const word64 k[2]) key[67] = c^key[65] ^ rotrConstant<3>(key[66]) ^ rotrConstant<4>(key[66]); } -//! \brief Subkey generation function -//! \details Used for SIMON-128 with 192-bit key and 69 rounds. A template was -//! not worthwhile because all instantiations would need specialization. -//! \param key empty subkey array -//! \param k user key array +/// \brief Subkey generation function +/// \details Used for SIMON-128 with 192-bit key and 69 rounds. A template was +/// not worthwhile because all instantiations would need specialization. +/// \param key empty subkey array +/// \param k user key array inline void SIMON128_ExpandKey_69R3K(word64 key[69], const word64 k[3]) { const word64 c = W64LIT(0xfffffffffffffffc); @@ -169,11 +169,11 @@ inline void SIMON128_ExpandKey_69R3K(word64 key[69], const word64 k[3]) key[68] = c ^ 1 ^ key[65] ^ rotrConstant<3>(key[67]) ^ rotrConstant<4>(key[67]); } -//! \brief Subkey generation function -//! \details Used for SIMON-128 with 256-bit key and 72 rounds. A template was -//! not worthwhile because all instantiations would need specialization. -//! \param key empty subkey array -//! \param k user key array +/// \brief Subkey generation function +/// \details Used for SIMON-128 with 256-bit key and 72 rounds. A template was +/// not worthwhile because all instantiations would need specialization. +/// \param key empty subkey array +/// \param k user key array inline void SIMON128_ExpandKey_72R4K(word64 key[72], const word64 k[4]) { const word64 c = W64LIT(0xfffffffffffffffc); diff --git a/simon.h b/simon.h index 7863c525..9758a11c 100644 --- a/simon.h +++ b/simon.h @@ -1,13 +1,13 @@ // simon.h - written and placed in the public domain by Jeffrey Walton -//! \file simon.h -//! \brief Classes for the Simon block cipher -//! \details Simon is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, -//! Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. -//! \sa The SIMON and SPECK Families of -//! Lightweight Block Ciphers and -//! The Simon and Speck GitHub -//! \since Crypto++ 6.0 +/// \file simon.h +/// \brief Classes for the Simon block cipher +/// \details Simon is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, +/// Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. +/// \sa The SIMON and SPECK Families of +/// Lightweight Block Ciphers and +/// The Simon and Speck GitHub +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_SIMON_H #define CRYPTOPP_SIMON_H @@ -22,13 +22,13 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SIMON_Info -//! \brief SIMON block cipher information -//! \tparam L block size of the cipher, in bytes -//! \tparam D default key length, in bytes -//! \tparam N minimum key length, in bytes -//! \tparam M maximum key length, in bytes -//! \since Crypto++ 6.0 +/// \class SIMON_Info +/// \brief SIMON block cipher information +/// \tparam L block size of the cipher, in bytes +/// \tparam D default key length, in bytes +/// \tparam N minimum key length, in bytes +/// \tparam M maximum key length, in bytes +/// \since Crypto++ 6.0 template struct SIMON_Info : public FixedBlockSize, VariableKeyLength { @@ -39,12 +39,12 @@ struct SIMON_Info : public FixedBlockSize, VariableKeyLength } }; -//! \class SIMON_Base -//! \brief SIMON block cipher base class -//! \tparam W the word type -//! \details User code should use SIMON64 or SIMON128 -//! \sa SIMON64, SIMON128, SIMON on the Crypto++ wiki -//! \since Crypto++ 6.0 +/// \class SIMON_Base +/// \brief SIMON block cipher base class +/// \tparam W the word type +/// \details User code should use SIMON64 or SIMON128 +/// \sa SIMON64, SIMON128, SIMON on the Crypto++ wiki +/// \since Crypto++ 6.0 template struct SIMON_Base { @@ -58,22 +58,22 @@ struct SIMON_Base unsigned int m_rounds; // number of rounds }; -//! \class SIMON64 -//! \brief SIMON 64-bit block cipher -//! \details Simon is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, -//! Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. -//! \details SIMON64 provides 64-bit block size. The valid key sizes are 96-bit and 128-bit. -//! \sa SIMON64, SIMON128, The SIMON and SIMON -//! Families of Lightweight Block Ciphers, -//! The Simon and Speck GitHub, SIMON on the -//! Crypto++ wiki -//! \since Crypto++ 6.0 +/// \class SIMON64 +/// \brief SIMON 64-bit block cipher +/// \details Simon is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, +/// Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. +/// \details SIMON64 provides 64-bit block size. The valid key sizes are 96-bit and 128-bit. +/// \sa SIMON64, SIMON128, The SIMON and SIMON +/// Families of Lightweight Block Ciphers, +/// The Simon and Speck GitHub, SIMON on the +/// Crypto++ wiki +/// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE SIMON64 : public SIMON_Info<8, 12, 12, 16>, public BlockCipherDocumentation { public: - //! \brief SIMON block cipher transformation functions - //! \details Provides implementation common to encryption and decryption - //! \since Crypto++ 6.0 + /// \brief SIMON block cipher transformation functions + /// \details Provides implementation common to encryption and decryption + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Base : protected SIMON_Base, public BlockCipherImpl > { public: @@ -86,20 +86,20 @@ public: void UncheckedSetKey(const byte *userKey, unsigned int keyLength, const NameValuePairs ¶ms); }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Enc : public Base { protected: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \brief Provides implementation for encryption transformation - //! \details Dec provides implementation for decryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Dec provides implementation for decryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Dec : public Base { protected: @@ -110,22 +110,22 @@ public: typedef BlockCipherFinal Decryption; }; -//! \class SIMON128 -//! \brief SIMON 128-bit block cipher -//! \details Simon is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, -//! Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. -//! \details SIMON128 provides 128-bit block size. The valid key sizes are 128-bit, 192-bit and 256-bit. -//! \sa SIMON64, SIMON128, The SIMON and SIMON -//! Families of Lightweight Block Ciphers, -//! The Simon and Speck GitHub, SIMON on the -//! Crypto++ wiki -//! \since Crypto++ 6.0 +/// \class SIMON128 +/// \brief SIMON 128-bit block cipher +/// \details Simon is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, +/// Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. +/// \details SIMON128 provides 128-bit block size. The valid key sizes are 128-bit, 192-bit and 256-bit. +/// \sa SIMON64, SIMON128, The SIMON and SIMON +/// Families of Lightweight Block Ciphers, +/// The Simon and Speck GitHub, SIMON on the +/// Crypto++ wiki +/// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE SIMON128 : public SIMON_Info<16, 16, 16, 32>, public BlockCipherDocumentation { public: - //! \brief SIMON block cipher transformation functions - //! \details Provides implementation common to encryption and decryption - //! \since Crypto++ 6.0 + /// \brief SIMON block cipher transformation functions + /// \details Provides implementation common to encryption and decryption + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Base : protected SIMON_Base, public BlockCipherImpl > { public: @@ -138,10 +138,10 @@ public: void UncheckedSetKey(const byte *userKey, unsigned int keyLength, const NameValuePairs ¶ms); }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Enc : public Base { protected: @@ -151,10 +151,10 @@ public: #endif }; - //! \brief Provides implementation for encryption transformation - //! \details Dec provides implementation for decryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Dec provides implementation for decryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Dec : public Base { protected: diff --git a/simple.h b/simple.h index 8e2cdd4b..ea8d6748 100644 --- a/simple.h +++ b/simple.h @@ -1,7 +1,7 @@ // simple.h - originally written and placed in the public domain by Wei Dai -//! \file simple.h -//! \brief Classes providing basic library services. +/// \file simple.h +/// \brief Classes providing basic library services. #ifndef CRYPTOPP_SIMPLE_H #define CRYPTOPP_SIMPLE_H @@ -18,10 +18,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class ClonableImpl -//! \brief Base class for identifying alogorithm -//! \tparam BASE base class from which to derive -//! \tparam DERIVED class which to clone +/// \class ClonableImpl +/// \brief Base class for identifying alogorithm +/// \tparam BASE base class from which to derive +/// \tparam DERIVED class which to clone template class CRYPTOPP_NO_VTABLE ClonableImpl : public BASE { @@ -29,61 +29,61 @@ public: Clonable * Clone() const {return new DERIVED(*static_cast(this));} }; -//! \class AlgorithmImpl -//! \brief Base class information -//! \tparam BASE an Algorithm derived class -//! \tparam ALGORITHM_INFO an Algorithm derived class -//! \details AlgorithmImpl provides StaticAlgorithmName from the template parameter BASE +/// \class AlgorithmImpl +/// \brief Base class information +/// \tparam BASE an Algorithm derived class +/// \tparam ALGORITHM_INFO an Algorithm derived class +/// \details AlgorithmImpl provides StaticAlgorithmName from the template parameter BASE template class CRYPTOPP_NO_VTABLE AlgorithmImpl : public BASE { public: - //! \brief The algorithm name - //! \returns the algorithm name - //! \details StaticAlgorithmName returns the algorithm's name as a static member function. - //! The name is taken from information provided by BASE. + /// \brief The algorithm name + /// \returns the algorithm name + /// \details StaticAlgorithmName returns the algorithm's name as a static member function. + /// The name is taken from information provided by BASE. static std::string CRYPTOPP_API StaticAlgorithmName() {return ALGORITHM_INFO::StaticAlgorithmName();} - //! \brief The algorithm name - //! \returns the algorithm name - //! \details AlgorithmName returns the algorithm's name as a member function. - //! The name is is acquired by calling StaticAlgorithmName. + /// \brief The algorithm name + /// \returns the algorithm name + /// \details AlgorithmName returns the algorithm's name as a member function. + /// The name is is acquired by calling StaticAlgorithmName. std::string AlgorithmName() const {return ALGORITHM_INFO::StaticAlgorithmName();} }; -//! \class InvalidKeyLength -//! \brief Exception thrown when an invalid key length is encountered +/// \class InvalidKeyLength +/// \brief Exception thrown when an invalid key length is encountered class CRYPTOPP_DLL InvalidKeyLength : public InvalidArgument { public: explicit InvalidKeyLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid key length") {} }; -//! \class InvalidRounds -//! \brief Exception thrown when an invalid number of rounds is encountered +/// \class InvalidRounds +/// \brief Exception thrown when an invalid number of rounds is encountered class CRYPTOPP_DLL InvalidRounds : public InvalidArgument { public: explicit InvalidRounds(const std::string &algorithm, unsigned int rounds) : InvalidArgument(algorithm + ": " + IntToString(rounds) + " is not a valid number of rounds") {} }; -//! \class InvalidBlockSize -//! \brief Exception thrown when an invalid block size is encountered +/// \class InvalidBlockSize +/// \brief Exception thrown when an invalid block size is encountered class CRYPTOPP_DLL InvalidBlockSize : public InvalidArgument { public: explicit InvalidBlockSize(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid block size") {} }; -//! \class InvalidPersonalizationLength -//! \brief Exception thrown when an invalid personalization string length is encountered +/// \class InvalidPersonalizationLength +/// \brief Exception thrown when an invalid personalization string length is encountered class CRYPTOPP_DLL InvalidPersonalizationLength : public InvalidArgument { public: explicit InvalidPersonalizationLength(const std::string &algorithm, size_t length) : InvalidArgument(algorithm + ": " + IntToString(length) + " is not a valid salt length") {} }; -//! \class InvalidSaltLength -//! \brief Exception thrown when an invalid salt length is encountered +/// \class InvalidSaltLength +/// \brief Exception thrown when an invalid salt length is encountered class CRYPTOPP_DLL InvalidSaltLength : public InvalidArgument { public: @@ -92,9 +92,9 @@ public: // ***************************** -//! \class Bufferless -//! \brief Base class for bufferless filters -//! \tparam T the class or type +/// \class Bufferless +/// \brief Base class for bufferless filters +/// \tparam T the class or type template class CRYPTOPP_NO_VTABLE Bufferless : public T { @@ -103,9 +103,9 @@ public: {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); return false;} }; -//! \class Unflushable -//! \brief Base class for unflushable filters -//! \tparam T the class or type +/// \class Unflushable +/// \brief Base class for unflushable filters +/// \tparam T the class or type template class CRYPTOPP_NO_VTABLE Unflushable : public T { @@ -129,10 +129,10 @@ protected: virtual bool InputBufferIsEmpty() const {return false;} }; -//! \class InputRejecting -//! \brief Base class for input rejecting filters -//! \tparam T the class or type -//! \details T should be a BufferedTransformation derived class +/// \class InputRejecting +/// \brief Base class for input rejecting filters +/// \tparam T the class or type +/// \details T should be a BufferedTransformation derived class template class CRYPTOPP_NO_VTABLE InputRejecting : public T { @@ -140,22 +140,22 @@ public: struct InputRejected : public NotImplemented {InputRejected() : NotImplemented("BufferedTransformation: this object doesn't allow input") {}}; - //! \name INPUT + /// \name INPUT //@{ - //! \brief Input a byte array for processing - //! \param inString the byte array to process - //! \param length the size of the string, in bytes - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one - //! \param blocking specifies whether the object should block when processing input - //! \throws InputRejected - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) - //! \details Internally, the default implementation throws InputRejected. + /// \brief Input a byte array for processing + /// \param inString the byte array to process + /// \param length the size of the string, in bytes + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one + /// \param blocking specifies whether the object should block when processing input + /// \throws InputRejected + /// \returns the number of bytes that remain in the block (i.e., bytes not processed) + /// \details Internally, the default implementation throws InputRejected. size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking) {CRYPTOPP_UNUSED(inString); CRYPTOPP_UNUSED(length); CRYPTOPP_UNUSED(messageEnd); CRYPTOPP_UNUSED(blocking); throw InputRejected();} //@} - //! \name SIGNALS + /// \name SIGNALS //@{ bool IsolatedFlush(bool hardFlush, bool blocking) {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); return false;} @@ -168,30 +168,30 @@ public: //@} }; -//! \class CustomFlushPropagation -//! \brief Interface for custom flush signals propagation -//! \tparam T BufferedTransformation derived class +/// \class CustomFlushPropagation +/// \brief Interface for custom flush signals propagation +/// \tparam T BufferedTransformation derived class template class CRYPTOPP_NO_VTABLE CustomFlushPropagation : public T { public: - //! \name SIGNALS + /// \name SIGNALS //@{ - //! \brief Flush buffered input and/or output, with signal propagation - //! \param hardFlush is used to indicate whether all data should be flushed - //! \param propagation the number of attached transformations the Flush() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. - //! \note Hard flushes must be used with care. It means try to process and output everything, even if - //! there may not be enough data to complete the action. For example, hard flushing a HexDecoder - //! would cause an error if you do it after inputing an odd number of hex encoded characters. - //! \note For some types of filters, like ZlibDecompressor, hard flushes can only - //! be done at "synchronization points". These synchronization points are positions in the data - //! stream that are created by hard flushes on the corresponding reverse filters, in this - //! example ZlibCompressor. This is useful when zlib compressed data is moved across a - //! network in packets and compression state is preserved across packets, as in the SSH2 protocol. + /// \brief Flush buffered input and/or output, with signal propagation + /// \param hardFlush is used to indicate whether all data should be flushed + /// \param propagation the number of attached transformations the Flush() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. + /// \note Hard flushes must be used with care. It means try to process and output everything, even if + /// there may not be enough data to complete the action. For example, hard flushing a HexDecoder + /// would cause an error if you do it after inputing an odd number of hex encoded characters. + /// \note For some types of filters, like ZlibDecompressor, hard flushes can only + /// be done at "synchronization points". These synchronization points are positions in the data + /// stream that are created by hard flushes on the corresponding reverse filters, in this + /// example ZlibCompressor. This is useful when zlib compressed data is moved across a + /// network in packets and compression state is preserved across packets, as in the SSH2 protocol. virtual bool Flush(bool hardFlush, int propagation=-1, bool blocking=true) =0; //@} @@ -201,21 +201,21 @@ private: {CRYPTOPP_UNUSED(hardFlush); CRYPTOPP_UNUSED(blocking); CRYPTOPP_ASSERT(false); return false;} }; -//! \class CustomSignalPropagation -//! \brief Interface for custom flush signals -//! \tparam T BufferedTransformation derived class +/// \class CustomSignalPropagation +/// \brief Interface for custom flush signals +/// \tparam T BufferedTransformation derived class template class CRYPTOPP_NO_VTABLE CustomSignalPropagation : public CustomFlushPropagation { public: - //! \brief Initialize or reinitialize this object, with signal propagation - //! \param parameters a set of NameValuePairs to initialize or reinitialize this object - //! \param propagation the number of attached transformations the Initialize() signal should be passed - //! \details Initialize() is used to initialize or reinitialize an object using a variable number of - //! arbitrarily typed arguments. The function avoids the need for multiple constructors providing - //! all possible combintations of configurable parameters. - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. + /// \brief Initialize or reinitialize this object, with signal propagation + /// \param parameters a set of NameValuePairs to initialize or reinitialize this object + /// \param propagation the number of attached transformations the Initialize() signal should be passed + /// \details Initialize() is used to initialize or reinitialize an object using a variable number of + /// arbitrarily typed arguments. The function avoids the need for multiple constructors providing + /// all possible combintations of configurable parameters. + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. virtual void Initialize(const NameValuePairs ¶meters=g_nullNameValuePairs, int propagation=-1) =0; private: @@ -223,10 +223,10 @@ private: {CRYPTOPP_UNUSED(parameters); CRYPTOPP_ASSERT(false);} }; -//! \class Multichannel -//! \brief Multiple channels support for custom signal processing -//! \tparam T the class or type -//! \details T should be a BufferedTransformation derived class +/// \class Multichannel +/// \brief Multiple channels support for custom signal processing +/// \tparam T the class or type +/// \details T should be a BufferedTransformation derived class template class CRYPTOPP_NO_VTABLE Multichannel : public CustomFlushPropagation { @@ -234,44 +234,44 @@ public: bool Flush(bool hardFlush, int propagation=-1, bool blocking=true) {return this->ChannelFlush(DEFAULT_CHANNEL, hardFlush, propagation, blocking);} - //! \brief Marks the end of a series of messages, with signal propagation - //! \param propagation the number of attached transformations the MessageSeriesEnd() signal should be passed - //! \param blocking specifies whether the object should block when processing input - //! \details Each object that receives the signal will perform its processing, decrement - //! propagation, and then pass the signal on to attached transformations if the value is not 0. - //! \details propagation count includes this object. Setting propagation to 1 means this - //! object only. Setting propagation to -1 means unlimited propagation. - //! \note There should be a MessageEnd() immediately before MessageSeriesEnd(). + /// \brief Marks the end of a series of messages, with signal propagation + /// \param propagation the number of attached transformations the MessageSeriesEnd() signal should be passed + /// \param blocking specifies whether the object should block when processing input + /// \details Each object that receives the signal will perform its processing, decrement + /// propagation, and then pass the signal on to attached transformations if the value is not 0. + /// \details propagation count includes this object. Setting propagation to 1 means this + /// object only. Setting propagation to -1 means unlimited propagation. + /// \note There should be a MessageEnd() immediately before MessageSeriesEnd(). bool MessageSeriesEnd(int propagation=-1, bool blocking=true) {return this->ChannelMessageSeriesEnd(DEFAULT_CHANNEL, propagation, blocking);} - //! \brief Request space which can be written into by the caller - //! \param size the requested size of the buffer - //! \details The purpose of this method is to help avoid extra memory allocations. - //! \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, - //! size is the requested size of the buffer. When the call returns, size is the size of - //! the array returned to the caller. - //! \details The base class implementation sets size to 0 and returns NULL. - //! \note Some objects, like ArraySink, cannot create a space because its fixed. In the case of - //! an ArraySink, the pointer to the array is returned and the size is remaining size. + /// \brief Request space which can be written into by the caller + /// \param size the requested size of the buffer + /// \details The purpose of this method is to help avoid extra memory allocations. + /// \details size is an \a IN and \a OUT parameter and used as a hint. When the call is made, + /// size is the requested size of the buffer. When the call returns, size is the size of + /// the array returned to the caller. + /// \details The base class implementation sets size to 0 and returns NULL. + /// \note Some objects, like ArraySink, cannot create a space because its fixed. In the case of + /// an ArraySink, the pointer to the array is returned and the size is remaining size. byte * CreatePutSpace(size_t &size) {return this->ChannelCreatePutSpace(DEFAULT_CHANNEL, size);} - //! \brief Input multiple bytes for processing - //! \param inString the byte buffer to process - //! \param length the size of the string, in bytes - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one - //! \param blocking specifies whether the object should block when processing input - //! \details Derived classes must implement Put2(). + /// \brief Input multiple bytes for processing + /// \param inString the byte buffer to process + /// \param length the size of the string, in bytes + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one + /// \param blocking specifies whether the object should block when processing input + /// \details Derived classes must implement Put2(). size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking) {return this->ChannelPut2(DEFAULT_CHANNEL, inString, length, messageEnd, blocking);} - //! \brief Input multiple bytes that may be modified by callee. - //! \param inString the byte buffer to process. - //! \param length the size of the string, in bytes. - //! \param messageEnd means how many filters to signal MessageEnd() to, including this one. - //! \param blocking specifies whether the object should block when processing input. - //! \details Internally, PutModifiable2() calls Put2(). + /// \brief Input multiple bytes that may be modified by callee. + /// \param inString the byte buffer to process. + /// \param length the size of the string, in bytes. + /// \param messageEnd means how many filters to signal MessageEnd() to, including this one. + /// \param blocking specifies whether the object should block when processing input. + /// \details Internally, PutModifiable2() calls Put2(). size_t PutModifiable2(byte *inString, size_t length, int messageEnd, bool blocking) {return this->ChannelPutModifiable2(DEFAULT_CHANNEL, inString, length, messageEnd, blocking);} @@ -289,15 +289,15 @@ public: virtual bool ChannelFlush(const std::string &channel, bool hardFlush, int propagation=-1, bool blocking=true) =0; }; -//! \class AutoSignaling -//! \brief Provides auto signaling support -//! \tparam T BufferedTransformation derived class +/// \class AutoSignaling +/// \brief Provides auto signaling support +/// \tparam T BufferedTransformation derived class template class CRYPTOPP_NO_VTABLE AutoSignaling : public T { public: - //! \brief Construct an AutoSignaling - //! \param propagation the propagation count + /// \brief Construct an AutoSignaling + /// \param propagation the propagation count AutoSignaling(int propagation=-1) : m_autoSignalPropagation(propagation) {} void SetAutoSignalPropagation(int propagation) @@ -309,12 +309,12 @@ private: int m_autoSignalPropagation; }; -//! \class Store -//! \brief Acts as a Source for pre-existing, static data +/// \class Store +/// \brief Acts as a Source for pre-existing, static data class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Store : public AutoSignaling > { public: - //! \brief Construct a Store + /// \brief Construct a Store Store() : m_messageEnd(false) {} void IsolatedInitialize(const NameValuePairs ¶meters) @@ -333,16 +333,16 @@ protected: bool m_messageEnd; }; -//! \class Sink -//! \brief Implementation of BufferedTransformation's attachment interface -//! \details Sink is a cornerstone of the Pipeline trinitiy. Data flows from -//! Sources, through Filters, and then terminates in Sinks. The difference -//! between a Source and Filter is a Source \a pumps data, while a Filter does -//! not. The difference between a Filter and a Sink is a Filter allows an -//! attached transformation, while a Sink does not. -//! \details A Sink doesnot produce any retrievable output. -//! \details See the discussion of BufferedTransformation in cryptlib.h for -//! more details. +/// \class Sink +/// \brief Implementation of BufferedTransformation's attachment interface +/// \details Sink is a cornerstone of the Pipeline trinitiy. Data flows from +/// Sources, through Filters, and then terminates in Sinks. The difference +/// between a Source and Filter is a Source \a pumps data, while a Filter does +/// not. The difference between a Filter and a Sink is a Filter allows an +/// attached transformation, while a Sink does not. +/// \details A Sink doesnot produce any retrievable output. +/// \details See the discussion of BufferedTransformation in cryptlib.h for +/// more details. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Sink : public BufferedTransformation { public: @@ -352,10 +352,10 @@ public: {CRYPTOPP_UNUSED(target); CRYPTOPP_UNUSED(begin); CRYPTOPP_UNUSED(end); CRYPTOPP_UNUSED(channel); CRYPTOPP_UNUSED(blocking); return 0;} }; -//! \class BitBucket -//! \brief Acts as an input discarding Filter or Sink -//! \details The BitBucket discards all input and returns 0 to the caller -//! to indicate all data was processed. +/// \class BitBucket +/// \brief Acts as an input discarding Filter or Sink +/// \details The BitBucket discards all input and returns 0 to the caller +/// to indicate all data was processed. class CRYPTOPP_DLL BitBucket : public Bufferless { public: diff --git a/siphash.h b/siphash.h index 5f36cd39..9bd190a4 100644 --- a/siphash.h +++ b/siphash.h @@ -1,27 +1,27 @@ // siphash.h - written and placed in public domain by Jeffrey Walton. -//! \file siphash.h -//! \brief Classes for SipHash message authentication code -//! \details SipHash computes a 64-bit or 128-bit message authentication code from a variable-length -//! message and 128-bit secret key. It was designed to be efficient even for short inputs, with -//! performance comparable to non-cryptographic hash functions. -//! \details To create a SipHash-2-4 object with a 64-bit MAC use code similar to the following. -//! 
  SecByteBlock key(16);
-//!   prng.GenerateBlock(key, key.size());
-//!
-//!   SipHash<2,4,false> hash(key, key.size());
-//!   hash.Update(...);
-//!   hash.Final(...);
-//! \details To create a SipHash-2-4 object with a 128-bit MAC use code similar to the following. -//! 
  SecByteBlock key(16);
-//!   prng.GenerateBlock(key, key.size());
-//!
-//!   SipHash<2,4,true> hash(key, key.size());
-//!   hash.Update(...);
-//!   hash.Final(...);
-//! \sa Jean-Philippe Aumasson and Daniel J. Bernstein SipHash: -//! a fast short-input PRF -//! \since Crypto++ 6.0 +/// \file siphash.h +/// \brief Classes for SipHash message authentication code +/// \details SipHash computes a 64-bit or 128-bit message authentication code from a variable-length +/// message and 128-bit secret key. It was designed to be efficient even for short inputs, with +/// performance comparable to non-cryptographic hash functions. +/// \details To create a SipHash-2-4 object with a 64-bit MAC use code similar to the following. +/// 
  SecByteBlock key(16);
+///   prng.GenerateBlock(key, key.size());
+///
+///   SipHash<2,4,false> hash(key, key.size());
+///   hash.Update(...);
+///   hash.Final(...);
+/// \details To create a SipHash-2-4 object with a 128-bit MAC use code similar to the following. +/// 
  SecByteBlock key(16);
+///   prng.GenerateBlock(key, key.size());
+///
+///   SipHash<2,4,true> hash(key, key.size());
+///   hash.Update(...);
+///   hash.Final(...);
+/// \sa Jean-Philippe Aumasson and Daniel J. Bernstein SipHash: +/// a fast short-input PRF +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_SIPHASH_H #define CRYPTOPP_SIPHASH_H @@ -32,9 +32,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SipHash_Info -//! \brief SipHash message authentication code information -//! \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size +/// \class SipHash_Info +/// \brief SipHash message authentication code information +/// \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size template class SipHash_Info : public FixedKeyLength<16> { @@ -43,11 +43,11 @@ public: CRYPTOPP_CONSTANT(DIGESTSIZE = (T_128bit ? 16 : 8)) }; -//! \class SipHash_Base -//! \brief SipHash message authentication code base class -//! \tparam C the number of compression rounds -//! \tparam D the number of finalization rounds -//! \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size +/// \class SipHash_Base +/// \brief SipHash message authentication code base class +/// \tparam C the number of compression rounds +/// \tparam D the number of finalization rounds +/// \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size template class SipHash_Base : public MessageAuthenticationCode, public SipHash_Info { @@ -115,41 +115,41 @@ private: size_t m_idx; }; -//! \class SipHash -//! \brief SipHash message authentication code -//! \tparam C the number of compression rounds -//! \tparam D the number of finalization rounds -//! \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size -//! \details SipHash computes a 64-bit or 128-bit message authentication code from a variable-length -//! message and 128-bit secret key. It was designed to be efficient even for short inputs, with -//! performance comparable to non-cryptographic hash functions. -//! \details To create a SipHash-2-4 object with a 64-bit MAC use code similar to the following. -//! 
  SecByteBlock key(16);
-//!   prng.GenerateBlock(key, key.size());
-//!
-//!   SipHash<2,4,false> hash(key, key.size());
-//!   hash.Update(...);
-//!   hash.Final(...);
-//! \details To create a SipHash-2-4 object with a 128-bit MAC use code similar to the following. -//! 
  SecByteBlock key(16);
-//!   prng.GenerateBlock(key, key.size());
-//!
-//!   SipHash<2,4,true> hash(key, key.size());
-//!   hash.Update(...);
-//!   hash.Final(...);
-//! \sa Jean-Philippe Aumasson and Daniel J. Bernstein SipHash: -//! a fast short-input PRF -//! \since Crypto++ 6.0 +/// \class SipHash +/// \brief SipHash message authentication code +/// \tparam C the number of compression rounds +/// \tparam D the number of finalization rounds +/// \tparam T_128bit flag indicating 128-bit (true) versus 64-bit (false) digest size +/// \details SipHash computes a 64-bit or 128-bit message authentication code from a variable-length +/// message and 128-bit secret key. It was designed to be efficient even for short inputs, with +/// performance comparable to non-cryptographic hash functions. +/// \details To create a SipHash-2-4 object with a 64-bit MAC use code similar to the following. +/// 
  SecByteBlock key(16);
+///   prng.GenerateBlock(key, key.size());
+///
+///   SipHash<2,4,false> hash(key, key.size());
+///   hash.Update(...);
+///   hash.Final(...);
+/// \details To create a SipHash-2-4 object with a 128-bit MAC use code similar to the following. +/// 
  SecByteBlock key(16);
+///   prng.GenerateBlock(key, key.size());
+///
+///   SipHash<2,4,true> hash(key, key.size());
+///   hash.Update(...);
+///   hash.Final(...);
+/// \sa Jean-Philippe Aumasson and Daniel J. Bernstein SipHash: +/// a fast short-input PRF +/// \since Crypto++ 6.0 template class SipHash : public SipHash_Base { public: - //! \brief Create a SipHash + /// \brief Create a SipHash SipHash() {this->UncheckedSetKey(NULLPTR, 0, g_nullNameValuePairs);} - //! \brief Create a SipHash - //! \param key a byte array used to key the cipher - //! \param length the size of the byte array, in bytes + /// \brief Create a SipHash + /// \param key a byte array used to key the cipher + /// \param length the size of the byte array, in bytes SipHash(const byte *key, unsigned int length) {this->UncheckedSetKey(key, length, g_nullNameValuePairs);} }; diff --git a/skipjack.h b/skipjack.h index 6fcf7031..01743224 100644 --- a/skipjack.h +++ b/skipjack.h @@ -1,7 +1,7 @@ // skipjack.h - originally written and placed in the public domain by Wei Dai -//! \file skipjack.h -//! \brief Classes for the SKIPJACK block cipher +/// \file skipjack.h +/// \brief Classes for the SKIPJACK block cipher #ifndef CRYPTOPP_SKIPJACK_H #define CRYPTOPP_SKIPJACK_H @@ -11,20 +11,20 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SKIPJACK_Info -//! \brief SKIPJACK block cipher information +/// \class SKIPJACK_Info +/// \brief SKIPJACK block cipher information struct SKIPJACK_Info : public FixedBlockSize<8>, public FixedKeyLength<10> { CRYPTOPP_DLL static const char * CRYPTOPP_API StaticAlgorithmName() {return "SKIPJACK";} }; -//! \class SKIPJACK -//! \brief SKIPJACK block cipher -//! \sa SKIPJACK +/// \class SKIPJACK +/// \brief SKIPJACK block cipher +/// \sa SKIPJACK class SKIPJACK : public SKIPJACK_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief SKIPJACK block cipher default operation + /// \class Base + /// \brief SKIPJACK block cipher default operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -37,8 +37,8 @@ class SKIPJACK : public SKIPJACK_Info, public BlockCipherDocumentation FixedSizeSecBlock tab; }; - //! \class Enc - //! \brief SKIPJACK block cipher encryption operation + /// \class Enc + /// \brief SKIPJACK block cipher encryption operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Enc : public Base { public: @@ -48,8 +48,8 @@ class SKIPJACK : public SKIPJACK_Info, public BlockCipherDocumentation static const word32 Te[4][256]; }; - //! \class Dec - //! \brief SKIPJACK block cipher decryption operation + /// \class Dec + /// \brief SKIPJACK block cipher decryption operation class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Dec : public Base { public: diff --git a/sm3.h b/sm3.h index 3db88ee4..8bfd09e9 100644 --- a/sm3.h +++ b/sm3.h @@ -3,13 +3,13 @@ // Based on code by Krzysztof Kwiatkowski and Jack Lloyd. // Also see https://tools.ietf.org/html/draft-shen-sm3-hash. -//! \file sm3.h -//! \brief Classes for the SM3 hash function -//! \details SM3 is a hash function designed by Xiaoyun Wang, et al. The hash is part of the -//! Chinese State Cryptography Administration portfolio. -//! \sa SM3 Hash Function and -//! Reference implementation using OpenSSL. -//! \since Crypto++ 6.0 +/// \file sm3.h +/// \brief Classes for the SM3 hash function +/// \details SM3 is a hash function designed by Xiaoyun Wang, et al. The hash is part of the +/// Chinese State Cryptography Administration portfolio. +/// \sa SM3 Hash Function and +/// Reference implementation using OpenSSL. +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_SM3_H #define CRYPTOPP_SM3_H @@ -19,38 +19,38 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SM3 -//! \brief SM3 hash function -//! \details SM3 is a hash function designed by Xiaoyun Wang, et al. The hash is part of the -//! Chinese State Cryptography Administration portfolio. -//! \sa SM3 Hash Function -//! \since Crypto++ 6.0 +/// \class SM3 +/// \brief SM3 hash function +/// \details SM3 is a hash function designed by Xiaoyun Wang, et al. The hash is part of the +/// Chinese State Cryptography Administration portfolio. +/// \sa SM3 Hash Function +/// \since Crypto++ 6.0 class SM3 : public IteratedHashWithStaticTransform { public: - //! \brief Initialize state array - //! \param state the state of the hash - //! \details InitState sets a state array to SHA256 initial values - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState() and Transform(). External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. + /// \brief Initialize state array + /// \param state the state of the hash + /// \details InitState sets a state array to SHA256 initial values + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState() and Transform(). External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. static void InitState(HashWordType *state); - //! \brief Operate the hash - //! \param digest the state of the hash - //! \param data the data to be digested - //! \details Transform() operates the hash on data. When the call is invoked - //! digest holds initial or current state. Upon return digest holds - //! the hash or updated state. - //! \details Hashes which derive from IteratedHashWithStaticTransform provide static - //! member functions InitState() and Transform(). External classes, like SEAL and MDC, - //! can initialize state with a user provided key and operate the hash on the data - //! with the user supplied state. + /// \brief Operate the hash + /// \param digest the state of the hash + /// \param data the data to be digested + /// \details Transform() operates the hash on data. When the call is invoked + /// digest holds initial or current state. Upon return digest holds + /// the hash or updated state. + /// \details Hashes which derive from IteratedHashWithStaticTransform provide static + /// member functions InitState() and Transform(). External classes, like SEAL and MDC, + /// can initialize state with a user provided key and operate the hash on the data + /// with the user supplied state. static void Transform(HashWordType *digest, const HashWordType *data); - //! \brief The algorithm name - //! \returns C-style string "SM3" + /// \brief The algorithm name + /// \returns C-style string "SM3" CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() { return "SM3"; } protected: diff --git a/sm4.h b/sm4.h index 425192a2..906dad7e 100644 --- a/sm4.h +++ b/sm4.h @@ -1,12 +1,12 @@ // sm4.h - written and placed in the public domain by Jeffrey Walton and Han Lulu -//! \file sm4.h -//! \brief Classes for the SM4 block cipher -//! \details SM4 is a block cipher designed by Xiaoyun Wang, et al. The block cipher is part of the -//! Chinese State Cryptography Administration portfolio. The cipher was formely known as SMS4. -//! \sa SMS4 Encryption Algorithm for Wireless Networks and -//! Reference implementation using OpenSSL. -//! \since Crypto++ 6.0 +/// \file sm4.h +/// \brief Classes for the SM4 block cipher +/// \details SM4 is a block cipher designed by Xiaoyun Wang, et al. The block cipher is part of the +/// Chinese State Cryptography Administration portfolio. The cipher was formely known as SMS4. +/// \sa SMS4 Encryption Algorithm for Wireless Networks and +/// Reference implementation using OpenSSL. +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_SM4_H #define CRYPTOPP_SM4_H @@ -17,9 +17,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SM4_Info -//! \brief SM4 block cipher information -//! \since Crypto++ 6.0 +/// \class SM4_Info +/// \brief SM4 block cipher information +/// \since Crypto++ 6.0 struct SM4_Info : public FixedBlockSize<16>, FixedKeyLength<16> { static const std::string StaticAlgorithmName() @@ -28,18 +28,18 @@ struct SM4_Info : public FixedBlockSize<16>, FixedKeyLength<16> } }; -//! \class SM4 -//! \brief Classes for the SM4 block cipher -//! \details SM4 is a block cipher designed by Xiaoyun Wang, et al. The block cipher is part of the -//! Chinese State Cryptography Administration portfolio. The cipher was formely known as SMS4. -//! \sa SMS4 Encryption Algorithm for Wireless Networks -//! \since Crypto++ 6.0 +/// \class SM4 +/// \brief Classes for the SM4 block cipher +/// \details SM4 is a block cipher designed by Xiaoyun Wang, et al. The block cipher is part of the +/// Chinese State Cryptography Administration portfolio. The cipher was formely known as SMS4. +/// \sa SMS4 Encryption Algorithm for Wireless Networks +/// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE SM4 : public SM4_Info, public BlockCipherDocumentation { public: - //! \brief SM4 block cipher transformation functions - //! \details Provides implementation common to encryption and decryption - //! \since Crypto++ 6.0 + /// \brief SM4 block cipher transformation functions + /// \details Provides implementation common to encryption and decryption + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { protected: @@ -49,20 +49,20 @@ public: mutable SecBlock > m_wspace; }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Enc : public Base { protected: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \brief Provides implementation for encryption transformation - //! \details Dec provides implementation for decryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Dec provides implementation for decryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Dec : public Base { protected: diff --git a/smartptr.h b/smartptr.h index cc7874fb..e5ee7705 100644 --- a/smartptr.h +++ b/smartptr.h @@ -1,8 +1,8 @@ // smartptr.h - originally written and placed in the public domain by Wei Dai -//! \file -//! \headerfile smartptr.h -//! \brief Classes for automatic resource management +/// \file +/// \headerfile smartptr.h +/// \brief Classes for automatic resource management #ifndef CRYPTOPP_SMARTPTR_H #define CRYPTOPP_SMARTPTR_H @@ -12,11 +12,11 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class simple_ptr -//! \brief Manages resources for a single object -//! \tparam T class or type -//! \details \p simple_ptr is used frequently in the library to manage resources and -//! ensure cleanup under the RAII pattern (Resource Acquisition Is Initialization). +/// \class simple_ptr +/// \brief Manages resources for a single object +/// \tparam T class or type +/// \details \p simple_ptr is used frequently in the library to manage resources and +/// ensure cleanup under the RAII pattern (Resource Acquisition Is Initialization). template class simple_ptr { public: @@ -30,12 +30,12 @@ public: T *m_p; }; -//! \class member_ptr -//! \brief Pointer that overloads operator -> -//! \tparam T class or type -//! \details member_ptr is used frequently in the library to avoid the issues related to -//! std::auto_ptr in C++11 (deprecated) and std::unique_ptr in C++03 (non-existent). -//! \bug Issue 48: "Use of auto_ptr causes dirty compile under C++11" +/// \class member_ptr +/// \brief Pointer that overloads operator -> +/// \tparam T class or type +/// \details member_ptr is used frequently in the library to avoid the issues related to +/// std::auto_ptr in C++11 (deprecated) and std::unique_ptr in C++03 (non-existent). +/// \bug Issue 48: "Use of auto_ptr causes dirty compile under C++11" template class member_ptr { public: @@ -73,9 +73,9 @@ template void member_ptr::reset(T *p) {delete m_p; m_p = p;} // ******************************************************** -//! \class value_ptr -//! \brief Value pointer -//! \tparam T class or type +/// \class value_ptr +/// \brief Value pointer +/// \tparam T class or type template class value_ptr : public member_ptr { public: @@ -101,10 +101,10 @@ template value_ptr& value_ptr::operator=(const value_ptr& rhs // ******************************************************** -//! \class clonable_ptr -//! \brief A pointer which can be copied and cloned -//! \tparam T class or type -//! \details \p T should adhere to the \p Clonable interface +/// \class clonable_ptr +/// \brief A pointer which can be copied and cloned +/// \tparam T class or type +/// \details \p T should adhere to the \p Clonable interface template class clonable_ptr : public member_ptr { public: @@ -126,11 +126,11 @@ template clonable_ptr& clonable_ptr::operator=(const clonable_pt // ******************************************************** -//! \class counted_ptr -//! \brief Reference counted pointer -//! \tparam T class or type -//! \details users should declare \p m_referenceCount as std::atomic -//! (or similar) under C++ 11 +/// \class counted_ptr +/// \brief Reference counted pointer +/// \tparam T class or type +/// \details users should declare \p m_referenceCount as std::atomic +/// (or similar) under C++ 11 template class counted_ptr { public: @@ -220,18 +220,18 @@ template counted_ptr & counted_ptr::operator=(const counted_ptr< // ******************************************************** -//! \class vector_ptr -//! \brief Manages resources for an array of objects -//! \tparam T class or type -//! \details \p vector_ptr is used frequently in the library to avoid large stack allocations, -//! and manage resources and ensure cleanup under the RAII pattern (Resource Acquisition -//! Is Initialization). +/// \class vector_ptr +/// \brief Manages resources for an array of objects +/// \tparam T class or type +/// \details \p vector_ptr is used frequently in the library to avoid large stack allocations, +/// and manage resources and ensure cleanup under the RAII pattern (Resource Acquisition +/// Is Initialization). template class vector_ptr { public: - //! Construct an arry of \p T - //! \param size the size of the array, in elements - //! \details If \p T is a Plain Old Dataype (POD), then the array is uninitialized. + /// Construct an arry of \p T + /// \param size the size of the array, in elements + /// \details If \p T is a Plain Old Dataype (POD), then the array is uninitialized. vector_ptr(size_t size=0) : m_size(size), m_ptr(new T[m_size]) {} ~vector_ptr() @@ -278,15 +278,15 @@ private: // ******************************************************** -//! \class vector_member_ptrs -//! \brief Manages resources for an array of objects -//! \tparam T class or type +/// \class vector_member_ptrs +/// \brief Manages resources for an array of objects +/// \tparam T class or type template class vector_member_ptrs { public: - //! Construct an arry of \p T - //! \param size the size of the array, in elements - //! \details If \p T is a Plain Old Dataype (POD), then the array is uninitialized. + /// Construct an arry of \p T + /// \param size the size of the array, in elements + /// \details If \p T is a Plain Old Dataype (POD), then the array is uninitialized. vector_member_ptrs(size_t size=0) : m_size(size), m_ptr(new member_ptr[size]) {} ~vector_member_ptrs() diff --git a/socketft.h b/socketft.h index c9942d8e..00c4fc27 100644 --- a/socketft.h +++ b/socketft.h @@ -41,11 +41,11 @@ const int SOCKET_ERROR = -1; typedef TYPE_OF_SOCKLEN_T socklen_t; // see config.h #endif -//! wrapper for Windows or Berkeley Sockets +/// wrapper for Windows or Berkeley Sockets class Socket { public: - //! exception thrown by Socket class + /// exception thrown by Socket class class Err : public OS_Error { public: @@ -100,15 +100,15 @@ public: {if (!result) HandleError(operation);} #endif - //! look up the port number given its name, returns 0 if not found + /// look up the port number given its name, returns 0 if not found static unsigned int PortNameToNumber(const char *name, const char *protocol="tcp"); - //! start Windows Sockets 2 + /// start Windows Sockets 2 static void StartSockets(); - //! calls WSACleanup for Windows Sockets + /// calls WSACleanup for Windows Sockets static void ShutdownSockets(); - //! returns errno or WSAGetLastError + /// returns errno or WSAGetLastError static int GetLastError(); - //! sets errno or calls WSASetLastError + /// sets errno or calls WSASetLastError static void SetLastError(int errorCode); protected: @@ -190,7 +190,7 @@ private: #endif }; -//! socket-based implementation of NetworkSource +/// socket-based implementation of NetworkSource class SocketSource : public NetworkSource, public Socket { public: @@ -206,7 +206,7 @@ private: SocketReceiver m_receiver; }; -//! socket-based implementation of NetworkSink +/// socket-based implementation of NetworkSink class SocketSink : public NetworkSink, public Socket { public: diff --git a/sosemanuk.h b/sosemanuk.h index 7a189be6..a3f590c0 100644 --- a/sosemanuk.h +++ b/sosemanuk.h @@ -1,8 +1,8 @@ // sosemanuk.h - originally written and placed in the public domain by Wei Dai -//! \file sosemanuk.h -//! \brief Classes for Sosemanuk stream cipher -//! \since Crypto++ 5.5 +/// \file sosemanuk.h +/// \brief Classes for Sosemanuk stream cipher +/// \since Crypto++ 5.5 #ifndef CRYPTOPP_SOSEMANUK_H #define CRYPTOPP_SOSEMANUK_H @@ -18,17 +18,17 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SosemanukInfo -//! \brief Sosemanuk stream cipher information - //! \since Crypto++ 5.5 +/// \class SosemanukInfo +/// \brief Sosemanuk stream cipher information + /// \since Crypto++ 5.5 struct SosemanukInfo : public VariableKeyLength<16, 1, 32, 1, SimpleKeyingInterface::UNIQUE_IV, 16> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "Sosemanuk";} }; -//! \class SosemanukPolicy -//! \brief Sosemanuk stream cipher implementation -//! \since Crypto++ 5.5 +/// \class SosemanukPolicy +/// \brief Sosemanuk stream cipher implementation +/// \since Crypto++ 5.5 class SosemanukPolicy : public AdditiveCipherConcretePolicy, public SosemanukInfo { protected: @@ -45,14 +45,14 @@ protected: FixedSizeAlignedSecBlock m_state; }; -//! \class Sosemanuk -//! \brief Sosemanuk stream cipher -//! \details is a stream cipher developed by Come Berbain, Olivier Billet, Anne Canteaut, Nicolas Courtois, -//! Henri Gilbert, Louis Goubin, Aline Gouget, Louis Granboulan, Cédric Lauradoux, Marine Minier, Thomas -//! Pornin and Hervé Sibert. Sosemanuk is one of the final four Profile 1 (software) ciphers selected for -//! the eSTREAM Portfolio. -//! \sa Sosemanuk -//! \since Crypto++ 5.5 +/// \class Sosemanuk +/// \brief Sosemanuk stream cipher +/// \details is a stream cipher developed by Come Berbain, Olivier Billet, Anne Canteaut, Nicolas Courtois, +/// Henri Gilbert, Louis Goubin, Aline Gouget, Louis Granboulan, Cédric Lauradoux, Marine Minier, Thomas +/// Pornin and Hervé Sibert. Sosemanuk is one of the final four Profile 1 (software) ciphers selected for +/// the eSTREAM Portfolio. +/// \sa Sosemanuk +/// \since Crypto++ 5.5 struct Sosemanuk : public SosemanukInfo, public SymmetricCipherDocumentation { typedef SymmetricCipherFinal >, SosemanukInfo> Encryption; diff --git a/speck.cpp b/speck.cpp index 884a4bbc..00e73a0c 100644 --- a/speck.cpp +++ b/speck.cpp @@ -25,13 +25,13 @@ using CryptoPP::word64; using CryptoPP::rotlConstant; using CryptoPP::rotrConstant; -//! \brief Forward round transformation -//! \tparam W word type -//! \details TF83() is the forward round transformation using a=8 and b=3 rotations. -//! The initial test implementation provided template parameters, but they were -//! removed because SPECK32 using a=7 and b=2 was not on the road map. The -//! additional template parameters also made calling SPECK_Encrypt and SPECK_Decrypt -//! kind of messy. +/// \brief Forward round transformation +/// \tparam W word type +/// \details TF83() is the forward round transformation using a=8 and b=3 rotations. +/// The initial test implementation provided template parameters, but they were +/// removed because SPECK32 using a=7 and b=2 was not on the road map. The +/// additional template parameters also made calling SPECK_Encrypt and SPECK_Decrypt +/// kind of messy. template inline void TF83(W& x, W& y, const W k) { @@ -41,13 +41,13 @@ inline void TF83(W& x, W& y, const W k) y ^= x; } -//! \brief Reverse round transformation -//! \tparam W word type -//! \details TR83() is the reverse round transformation using a=8 and b=3 rotations. -//! The initial test implementation provided template parameters, but they were -//! removed because SPECK32 using a=7 and b=2 was not on the road map. The -//! additional template parameters also made calling SPECK_Encrypt and SPECK_Decrypt -//! kind of messy. +/// \brief Reverse round transformation +/// \tparam W word type +/// \details TR83() is the reverse round transformation using a=8 and b=3 rotations. +/// The initial test implementation provided template parameters, but they were +/// removed because SPECK32 using a=7 and b=2 was not on the road map. The +/// additional template parameters also made calling SPECK_Encrypt and SPECK_Decrypt +/// kind of messy. template inline void TR83(W& x, W& y, const W k) { @@ -57,12 +57,12 @@ inline void TR83(W& x, W& y, const W k) x = rotlConstant<8>(x); } -//! \brief Forward transformation -//! \tparam W word type -//! \tparam R number of rounds -//! \param c output array -//! \param p input array -//! \param k subkey array +/// \brief Forward transformation +/// \tparam W word type +/// \tparam R number of rounds +/// \param c output array +/// \param p input array +/// \param k subkey array template inline void SPECK_Encrypt(W c[2], const W p[2], const W k[R]) { @@ -73,12 +73,12 @@ inline void SPECK_Encrypt(W c[2], const W p[2], const W k[R]) TF83(c[0], c[1], k[i]); } -//! \brief Reverse transformation -//! \tparam W word type -//! \tparam R number of rounds -//! \param p output array -//! \param c input array -//! \param k subkey array +/// \brief Reverse transformation +/// \tparam W word type +/// \tparam R number of rounds +/// \param p output array +/// \param c input array +/// \param k subkey array template inline void SPECK_Decrypt(W p[2], const W c[2], const W k[R]) { @@ -89,12 +89,12 @@ inline void SPECK_Decrypt(W p[2], const W c[2], const W k[R]) TR83(p[0], p[1], k[i]); } -//! \brief Subkey generation function -//! \details Used when the user key consists of 2 words -//! \tparam W word type -//! \tparam R number of rounds -//! \param key empty subkey array -//! \param k user key array +/// \brief Subkey generation function +/// \details Used when the user key consists of 2 words +/// \tparam W word type +/// \tparam R number of rounds +/// \param key empty subkey array +/// \param k user key array template inline void SPECK_ExpandKey_2W(W key[R], const W k[2]) { @@ -109,12 +109,12 @@ inline void SPECK_ExpandKey_2W(W key[R], const W k[2]) key[R-1]=A; } -//! \brief Subkey generation function -//! \details Used when the user key consists of 3 words -//! \tparam W word type -//! \tparam R number of rounds -//! \param key empty subkey array -//! \param k user key array +/// \brief Subkey generation function +/// \details Used when the user key consists of 3 words +/// \tparam W word type +/// \tparam R number of rounds +/// \param key empty subkey array +/// \param k user key array template inline void SPECK_ExpandKey_3W(W key[R], const W k[3]) { @@ -136,12 +136,12 @@ inline void SPECK_ExpandKey_3W(W key[R], const W k[3]) } } -//! \brief Subkey generation function -//! \details Used when the user key consists of 4 words -//! \tparam W word type -//! \tparam R number of rounds -//! \param key empty subkey array -//! \param k user key array +/// \brief Subkey generation function +/// \details Used when the user key consists of 4 words +/// \tparam W word type +/// \tparam R number of rounds +/// \param key empty subkey array +/// \param k user key array template inline void SPECK_ExpandKey_4W(W key[R], const W k[4]) { diff --git a/speck.h b/speck.h index 108c82ec..ef78fb10 100644 --- a/speck.h +++ b/speck.h @@ -1,13 +1,13 @@ // speck.h - written and placed in the public domain by Jeffrey Walton -//! \file speck.h -//! \brief Classes for the Speck block cipher -//! \details Speck is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, -//! Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. -//! \sa The SIMON and SPECK Families of -//! Lightweight Block Ciphers and -//! The Simon and Speck GitHub -//! \since Crypto++ 6.0 +/// \file speck.h +/// \brief Classes for the Speck block cipher +/// \details Speck is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, +/// Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. +/// \sa The SIMON and SPECK Families of +/// Lightweight Block Ciphers and +/// The Simon and Speck GitHub +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_SPECK_H #define CRYPTOPP_SPECK_H @@ -22,13 +22,13 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class SPECK_Info -//! \brief SPECK block cipher information -//! \tparam L block size of the cipher, in bytes -//! \tparam D default key length, in bytes -//! \tparam N minimum key length, in bytes -//! \tparam M maximum key length, in bytes -//! \since Crypto++ 6.0 +/// \class SPECK_Info +/// \brief SPECK block cipher information +/// \tparam L block size of the cipher, in bytes +/// \tparam D default key length, in bytes +/// \tparam N minimum key length, in bytes +/// \tparam M maximum key length, in bytes +/// \since Crypto++ 6.0 template struct SPECK_Info : public FixedBlockSize, VariableKeyLength { @@ -39,12 +39,12 @@ struct SPECK_Info : public FixedBlockSize, VariableKeyLength } }; -//! \class SPECK_Base -//! \brief SPECK block cipher base class -//! \tparam W the word type -//! \details User code should use SPECK64 or SPECK128 -//! \sa SPECK64, SPECK128, SPECK -//! \since Crypto++ 6.0 +/// \class SPECK_Base +/// \brief SPECK block cipher base class +/// \tparam W the word type +/// \details User code should use SPECK64 or SPECK128 +/// \sa SPECK64, SPECK128, SPECK +/// \since Crypto++ 6.0 template struct SPECK_Base { @@ -58,22 +58,22 @@ struct SPECK_Base unsigned int m_rounds; // number of rounds }; -//! \class SPECK64 -//! \brief SPECK 64-bit block cipher -//! \details Speck is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, -//! Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. -//! \details SPECK64 provides 64-bit block size. The valid key sizes are 96-bit and 128-bit. -//! \sa SPECK64, SPECK128, The SIMON and SPECK -//! Families of Lightweight Block Ciphers, -//! The Simon and Speck GitHub, SPECK on the -//! Crypto++ wiki -//! \since Crypto++ 6.0 +/// \class SPECK64 +/// \brief SPECK 64-bit block cipher +/// \details Speck is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, +/// Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. +/// \details SPECK64 provides 64-bit block size. The valid key sizes are 96-bit and 128-bit. +/// \sa SPECK64, SPECK128, The SIMON and SPECK +/// Families of Lightweight Block Ciphers, +/// The Simon and Speck GitHub, SPECK on the +/// Crypto++ wiki +/// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE SPECK64 : public SPECK_Info<8, 12, 12, 16>, public BlockCipherDocumentation { public: - //! \brief SPECK block cipher transformation functions - //! \details Provides implementation common to encryption and decryption - //! \since Crypto++ 6.0 + /// \brief SPECK block cipher transformation functions + /// \details Provides implementation common to encryption and decryption + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Base : protected SPECK_Base, public BlockCipherImpl > { public: @@ -86,20 +86,20 @@ public: void UncheckedSetKey(const byte *userKey, unsigned int keyLength, const NameValuePairs ¶ms); }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Enc : public Base { protected: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \brief Provides implementation for encryption transformation - //! \details Dec provides implementation for decryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Dec provides implementation for decryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Dec : public Base { protected: @@ -110,22 +110,22 @@ public: typedef BlockCipherFinal Decryption; }; -//! \class SPECK128 -//! \brief SPECK 128-bit block cipher -//! \details Speck is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, -//! Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. -//! \details SPECK128 provides 128-bit block size. The valid key sizes are 128-bit, 192-bit and 256-bit. -//! \sa SPECK64, SPECK128, The SIMON and SPECK -//! Families of Lightweight Block Ciphers, -//! The Simon and Speck GitHub, SPECK on the -//! Crypto++ wiki -//! \since Crypto++ 6.0 +/// \class SPECK128 +/// \brief SPECK 128-bit block cipher +/// \details Speck is a block cipher designed by Ray Beaulieu, Douglas Shors, Jason Smith, +/// Stefan Treatman-Clark, Bryan Weeks and Louis Wingers. +/// \details SPECK128 provides 128-bit block size. The valid key sizes are 128-bit, 192-bit and 256-bit. +/// \sa SPECK64, SPECK128, The SIMON and SPECK +/// Families of Lightweight Block Ciphers, +/// The Simon and Speck GitHub, SPECK on the +/// Crypto++ wiki +/// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE SPECK128 : public SPECK_Info<16, 16, 16, 32>, public BlockCipherDocumentation { public: - //! \brief SPECK block cipher transformation functions - //! \details Provides implementation common to encryption and decryption - //! \since Crypto++ 6.0 + /// \brief SPECK block cipher transformation functions + /// \details Provides implementation common to encryption and decryption + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Base : protected SPECK_Base, public BlockCipherImpl > { public: @@ -138,10 +138,10 @@ public: void UncheckedSetKey(const byte *userKey, unsigned int keyLength, const NameValuePairs ¶ms); }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Enc : public Base { protected: @@ -151,10 +151,10 @@ public: #endif }; - //! \brief Provides implementation for encryption transformation - //! \details Dec provides implementation for decryption transformation. All key - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Dec provides implementation for decryption transformation. All key + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Dec : public Base { protected: diff --git a/square.h b/square.h index cb107f06..5e0147bf 100644 --- a/square.h +++ b/square.h @@ -1,7 +1,7 @@ // square.h - originally written and placed in the public domain by Wei Dai -//! \file square.h -//! \brief Classes for the Square block cipher +/// \file square.h +/// \brief Classes for the Square block cipher #ifndef CRYPTOPP_SQUARE_H #define CRYPTOPP_SQUARE_H @@ -11,16 +11,16 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Square_Info -//! \brief Square block cipher information +/// \class Square_Info +/// \brief Square block cipher information struct Square_Info : public FixedBlockSize<16>, public FixedKeyLength<16>, FixedRounds<8> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "Square";} }; -//! \class Square -//! \brief Square block cipher -//! \sa Square +/// \class Square +/// \brief Square block cipher +/// \sa Square class Square : public Square_Info, public BlockCipherDocumentation { class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl diff --git a/strciphr.h b/strciphr.h index 10082907..30f581fa 100644 --- a/strciphr.h +++ b/strciphr.h @@ -1,29 +1,29 @@ // strciphr.h - originally written and placed in the public domain by Wei Dai -//! \file strciphr.h -//! \brief Classes for implementing stream ciphers -//! \details This file contains helper classes for implementing stream ciphers. -//! All this infrastructure may look very complex compared to what's in Crypto++ 4.x, -//! but stream ciphers implementations now support a lot of new functionality, -//! including better performance (minimizing copying), resetting of keys and IVs, and methods to -//! query which features are supported by a cipher. -//! \details Here's an explanation of these classes. The word "policy" is used here to mean a class with a -//! set of methods that must be implemented by individual stream cipher implementations. -//! This is usually much simpler than the full stream cipher API, which is implemented by -//! either AdditiveCipherTemplate or CFB_CipherTemplate using the policy. So for example, an -//! implementation of SEAL only needs to implement the AdditiveCipherAbstractPolicy interface -//! (since it's an additive cipher, i.e., it xors a keystream into the plaintext). -//! See this line in seal.h: -//! 
-//!     typedef SymmetricCipherFinal\, AdditiveCipherTemplate\<\> \> \> Encryption;
-//!
-//! \details AdditiveCipherTemplate and CFB_CipherTemplate are designed so that they don't need -//! to take a policy class as a template parameter (although this is allowed), so that -//! their code is not duplicated for each new cipher. Instead they each -//! get a reference to an abstract policy interface by calling AccessPolicy() on itself, so -//! AccessPolicy() must be overridden to return the actual policy reference. This is done -//! by the ConceretePolicyHolder class. Finally, SymmetricCipherFinal implements the constructors and -//! other functions that must be implemented by the most derived class. +/// \file strciphr.h +/// \brief Classes for implementing stream ciphers +/// \details This file contains helper classes for implementing stream ciphers. +/// All this infrastructure may look very complex compared to what's in Crypto++ 4.x, +/// but stream ciphers implementations now support a lot of new functionality, +/// including better performance (minimizing copying), resetting of keys and IVs, and methods to +/// query which features are supported by a cipher. +/// \details Here's an explanation of these classes. The word "policy" is used here to mean a class with a +/// set of methods that must be implemented by individual stream cipher implementations. +/// This is usually much simpler than the full stream cipher API, which is implemented by +/// either AdditiveCipherTemplate or CFB_CipherTemplate using the policy. So for example, an +/// implementation of SEAL only needs to implement the AdditiveCipherAbstractPolicy interface +/// (since it's an additive cipher, i.e., it xors a keystream into the plaintext). +/// See this line in seal.h: +/// 
+///     typedef SymmetricCipherFinal\, AdditiveCipherTemplate\<\> \> \> Encryption;
+///
+/// \details AdditiveCipherTemplate and CFB_CipherTemplate are designed so that they don't need +/// to take a policy class as a template parameter (although this is allowed), so that +/// their code is not duplicated for each new cipher. Instead they each +/// get a reference to an abstract policy interface by calling AccessPolicy() on itself, so +/// AccessPolicy() must be overridden to return the actual policy reference. This is done +/// by the ConceretePolicyHolder class. Finally, SymmetricCipherFinal implements the constructors and +/// other functions that must be implemented by the most derived class. #ifndef CRYPTOPP_STRCIPHR_H #define CRYPTOPP_STRCIPHR_H @@ -42,10 +42,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class AbstractPolicyHolder -//! \brief Access a stream cipher policy object -//! \tparam POLICY_INTERFACE class implementing AbstractPolicyHolder -//! \tparam BASE class or type to use as a base class +/// \class AbstractPolicyHolder +/// \brief Access a stream cipher policy object +/// \tparam POLICY_INTERFACE class implementing AbstractPolicyHolder +/// \tparam BASE class or type to use as a base class template class CRYPTOPP_NO_VTABLE AbstractPolicyHolder : public BASE { @@ -58,10 +58,10 @@ protected: virtual POLICY_INTERFACE & AccessPolicy() =0; }; -//! \class ConcretePolicyHolder -//! \brief Stream cipher policy object -//! \tparam POLICY class implementing AbstractPolicyHolder -//! \tparam BASE class or type to use as a base class +/// \class ConcretePolicyHolder +/// \brief Stream cipher policy object +/// \tparam POLICY class implementing AbstractPolicyHolder +/// \tparam BASE class or type to use as a base class template class ConcretePolicyHolder : public BASE, protected POLICY { @@ -72,115 +72,115 @@ protected: POLICY_INTERFACE & AccessPolicy() {return *this;} }; -//! \brief Keystream operation flags -//! \sa AdditiveCipherAbstractPolicy::GetBytesPerIteration(), AdditiveCipherAbstractPolicy::GetOptimalBlockSize() -//! and AdditiveCipherAbstractPolicy::GetAlignment() +/// \brief Keystream operation flags +/// \sa AdditiveCipherAbstractPolicy::GetBytesPerIteration(), AdditiveCipherAbstractPolicy::GetOptimalBlockSize() +/// and AdditiveCipherAbstractPolicy::GetAlignment() enum KeystreamOperationFlags { - //! \brief Output buffer is aligned + /// \brief Output buffer is aligned OUTPUT_ALIGNED=1, - //! \brief Input buffer is aligned + /// \brief Input buffer is aligned INPUT_ALIGNED=2, - //! \brief Input buffer is NULL + /// \brief Input buffer is NULL INPUT_NULL = 4 }; -//! \brief Keystream operation flags -//! \sa AdditiveCipherAbstractPolicy::GetBytesPerIteration(), AdditiveCipherAbstractPolicy::GetOptimalBlockSize() -//! and AdditiveCipherAbstractPolicy::GetAlignment() +/// \brief Keystream operation flags +/// \sa AdditiveCipherAbstractPolicy::GetBytesPerIteration(), AdditiveCipherAbstractPolicy::GetOptimalBlockSize() +/// and AdditiveCipherAbstractPolicy::GetAlignment() enum KeystreamOperation { - //! \brief Wirte the keystream to the output buffer, input is NULL + /// \brief Wirte the keystream to the output buffer, input is NULL WRITE_KEYSTREAM = INPUT_NULL, - //! \brief Wirte the keystream to the aligned output buffer, input is NULL + /// \brief Wirte the keystream to the aligned output buffer, input is NULL WRITE_KEYSTREAM_ALIGNED = INPUT_NULL | OUTPUT_ALIGNED, - //! \brief XOR the input buffer and keystream, write to the output buffer + /// \brief XOR the input buffer and keystream, write to the output buffer XOR_KEYSTREAM = 0, - //! \brief XOR the aligned input buffer and keystream, write to the output buffer + /// \brief XOR the aligned input buffer and keystream, write to the output buffer XOR_KEYSTREAM_INPUT_ALIGNED = INPUT_ALIGNED, - //! \brief XOR the input buffer and keystream, write to the aligned output buffer + /// \brief XOR the input buffer and keystream, write to the aligned output buffer XOR_KEYSTREAM_OUTPUT_ALIGNED= OUTPUT_ALIGNED, - //! \brief XOR the aligned input buffer and keystream, write to the aligned output buffer + /// \brief XOR the aligned input buffer and keystream, write to the aligned output buffer XOR_KEYSTREAM_BOTH_ALIGNED = OUTPUT_ALIGNED | INPUT_ALIGNED}; -//! \class AdditiveCipherAbstractPolicy -//! \brief Policy object for additive stream ciphers +/// \class AdditiveCipherAbstractPolicy +/// \brief Policy object for additive stream ciphers struct CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AdditiveCipherAbstractPolicy { virtual ~AdditiveCipherAbstractPolicy() {} - //! \brief Provides data alignment requirements - //! \returns data alignment requirements, in bytes - //! \details Internally, the default implementation returns 1. If the stream cipher is implemented - //! using an SSE2 ASM or intrinsics, then the value returned is usually 16. + /// \brief Provides data alignment requirements + /// \returns data alignment requirements, in bytes + /// \details Internally, the default implementation returns 1. If the stream cipher is implemented + /// using an SSE2 ASM or intrinsics, then the value returned is usually 16. virtual unsigned int GetAlignment() const {return 1;} - //! \brief Provides number of bytes operated upon during an iteration - //! \returns bytes operated upon during an iteration, in bytes - //! \sa GetOptimalBlockSize() + /// \brief Provides number of bytes operated upon during an iteration + /// \returns bytes operated upon during an iteration, in bytes + /// \sa GetOptimalBlockSize() virtual unsigned int GetBytesPerIteration() const =0; - //! \brief Provides number of ideal bytes to process - //! \returns the ideal number of bytes to process - //! \details Internally, the default implementation returns GetBytesPerIteration() - //! \sa GetBytesPerIteration() + /// \brief Provides number of ideal bytes to process + /// \returns the ideal number of bytes to process + /// \details Internally, the default implementation returns GetBytesPerIteration() + /// \sa GetBytesPerIteration() virtual unsigned int GetOptimalBlockSize() const {return GetBytesPerIteration();} - //! \brief Provides buffer size based on iterations - //! \returns the buffer size based on iterations, in bytes + /// \brief Provides buffer size based on iterations + /// \returns the buffer size based on iterations, in bytes virtual unsigned int GetIterationsToBuffer() const =0; - //! \brief Generate the keystream - //! \param keystream the key stream - //! \param iterationCount the number of iterations to generate the key stream - //! \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream() + /// \brief Generate the keystream + /// \param keystream the key stream + /// \param iterationCount the number of iterations to generate the key stream + /// \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream() virtual void WriteKeystream(byte *keystream, size_t iterationCount) {OperateKeystream(KeystreamOperation(INPUT_NULL | (KeystreamOperationFlags)IsAlignedOn(keystream, GetAlignment())), keystream, NULLPTR, iterationCount);} - //! \brief Flag indicating - //! \returns true if the stream can be generated independent of the transformation input, false otherwise - //! \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream() + /// \brief Flag indicating + /// \returns true if the stream can be generated independent of the transformation input, false otherwise + /// \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream() virtual bool CanOperateKeystream() const {return false;} - //! \brief Operates the keystream - //! \param operation the operation with additional flags - //! \param output the output buffer - //! \param input the input buffer - //! \param iterationCount the number of iterations to perform on the input - //! \details OperateKeystream() will attempt to operate upon GetOptimalBlockSize() buffer, - //! which will be derived from GetBytesPerIteration(). - //! \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream(), KeystreamOperation() + /// \brief Operates the keystream + /// \param operation the operation with additional flags + /// \param output the output buffer + /// \param input the input buffer + /// \param iterationCount the number of iterations to perform on the input + /// \details OperateKeystream() will attempt to operate upon GetOptimalBlockSize() buffer, + /// which will be derived from GetBytesPerIteration(). + /// \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream(), KeystreamOperation() virtual void OperateKeystream(KeystreamOperation operation, byte *output, const byte *input, size_t iterationCount) {CRYPTOPP_UNUSED(operation); CRYPTOPP_UNUSED(output); CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(iterationCount); CRYPTOPP_ASSERT(false);} - //! \brief Key the cipher - //! \param params set of NameValuePairs use to initialize this object - //! \param key a byte array used to key the cipher - //! \param length the size of the key array + /// \brief Key the cipher + /// \param params set of NameValuePairs use to initialize this object + /// \param key a byte array used to key the cipher + /// \param length the size of the key array virtual void CipherSetKey(const NameValuePairs ¶ms, const byte *key, size_t length) =0; - //! \brief Resynchronize the cipher - //! \param keystreamBuffer the keystream buffer - //! \param iv a byte array used to resynchronize the cipher - //! \param length the size of the IV array + /// \brief Resynchronize the cipher + /// \param keystreamBuffer the keystream buffer + /// \param iv a byte array used to resynchronize the cipher + /// \param length the size of the IV array virtual void CipherResynchronize(byte *keystreamBuffer, const byte *iv, size_t length) {CRYPTOPP_UNUSED(keystreamBuffer); CRYPTOPP_UNUSED(iv); CRYPTOPP_UNUSED(length); throw NotImplemented("SimpleKeyingInterface: this object doesn't support resynchronization");} - //! \brief Flag indicating random access - //! \returns true if the cipher is seekable, false otherwise - //! \sa SeekToIteration() + /// \brief Flag indicating random access + /// \returns true if the cipher is seekable, false otherwise + /// \sa SeekToIteration() virtual bool CipherIsRandomAccess() const =0; - //! \brief Seeks to a random position in the stream - //! \sa CipherIsRandomAccess() + /// \brief Seeks to a random position in the stream + /// \sa CipherIsRandomAccess() virtual void SeekToIteration(lword iterationCount) {CRYPTOPP_UNUSED(iterationCount); CRYPTOPP_ASSERT(!CipherIsRandomAccess()); throw NotImplemented("StreamTransformation: this object doesn't support random access");} }; -//! \class AdditiveCipherConcretePolicy -//! \brief Base class for additive stream ciphers -//! \tparam WT word type -//! \tparam W count of words -//! \tparam X bytes per iteration count -//! \tparam BASE AdditiveCipherAbstractPolicy derived base class +/// \class AdditiveCipherConcretePolicy +/// \brief Base class for additive stream ciphers +/// \tparam WT word type +/// \tparam W count of words +/// \tparam X bytes per iteration count +/// \tparam BASE AdditiveCipherAbstractPolicy derived base class template struct CRYPTOPP_NO_VTABLE AdditiveCipherConcretePolicy : public BASE { @@ -188,49 +188,49 @@ struct CRYPTOPP_NO_VTABLE AdditiveCipherConcretePolicy : public BASE CRYPTOPP_CONSTANT(BYTES_PER_ITERATION = sizeof(WordType) * W) #if !(CRYPTOPP_BOOL_X86 || CRYPTOPP_BOOL_X64) - //! \brief Provides data alignment requirements - //! \returns data alignment requirements, in bytes - //! \details Internally, the default implementation returns 1. If the stream cipher is implemented - //! using an SSE2 ASM or intrinsics, then the value returned is usually 16. + /// \brief Provides data alignment requirements + /// \returns data alignment requirements, in bytes + /// \details Internally, the default implementation returns 1. If the stream cipher is implemented + /// using an SSE2 ASM or intrinsics, then the value returned is usually 16. unsigned int GetAlignment() const {return GetAlignmentOf();} #endif - //! \brief Provides number of bytes operated upon during an iteration - //! \returns bytes operated upon during an iteration, in bytes - //! \sa GetOptimalBlockSize() + /// \brief Provides number of bytes operated upon during an iteration + /// \returns bytes operated upon during an iteration, in bytes + /// \sa GetOptimalBlockSize() unsigned int GetBytesPerIteration() const {return BYTES_PER_ITERATION;} - //! \brief Provides buffer size based on iterations - //! \returns the buffer size based on iterations, in bytes + /// \brief Provides buffer size based on iterations + /// \returns the buffer size based on iterations, in bytes unsigned int GetIterationsToBuffer() const {return X;} - //! \brief Flag indicating - //! \returns true if the stream can be generated independent of the transformation input, false otherwise - //! \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream() + /// \brief Flag indicating + /// \returns true if the stream can be generated independent of the transformation input, false otherwise + /// \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream() bool CanOperateKeystream() const {return true;} - //! \brief Operates the keystream - //! \param operation the operation with additional flags - //! \param output the output buffer - //! \param input the input buffer - //! \param iterationCount the number of iterations to perform on the input - //! \details OperateKeystream() will attempt to operate upon GetOptimalBlockSize() buffer, - //! which will be derived from GetBytesPerIteration(). - //! \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream(), KeystreamOperation() + /// \brief Operates the keystream + /// \param operation the operation with additional flags + /// \param output the output buffer + /// \param input the input buffer + /// \param iterationCount the number of iterations to perform on the input + /// \details OperateKeystream() will attempt to operate upon GetOptimalBlockSize() buffer, + /// which will be derived from GetBytesPerIteration(). + /// \sa CanOperateKeystream(), OperateKeystream(), WriteKeystream(), KeystreamOperation() virtual void OperateKeystream(KeystreamOperation operation, byte *output, const byte *input, size_t iterationCount) =0; }; -//! \brief Helper macro to implement OperateKeystream +/// \brief Helper macro to implement OperateKeystream #define CRYPTOPP_KEYSTREAM_OUTPUT_WORD(x, b, i, a) \ PutWord(bool(x & OUTPUT_ALIGNED), b, output+i*sizeof(WordType), (x & INPUT_NULL) ? (a) : (a) ^ GetWord(bool(x & INPUT_ALIGNED), b, input+i*sizeof(WordType))); -//! \brief Helper macro to implement OperateKeystream +/// \brief Helper macro to implement OperateKeystream #define CRYPTOPP_KEYSTREAM_OUTPUT_XMM(x, i, a) {\ __m128i t = (x & INPUT_NULL) ? a : _mm_xor_si128(a, (x & INPUT_ALIGNED) ? _mm_load_si128((__m128i *)input+i) : _mm_loadu_si128((__m128i *)input+i));\ if (x & OUTPUT_ALIGNED) _mm_store_si128((__m128i *)output+i, t);\ else _mm_storeu_si128((__m128i *)output+i, t);} -//! \brief Helper macro to implement OperateKeystream +/// \brief Helper macro to implement OperateKeystream #define CRYPTOPP_KEYSTREAM_OUTPUT_SWITCH(x, y) \ switch (operation) \ { \ @@ -259,75 +259,75 @@ struct CRYPTOPP_NO_VTABLE AdditiveCipherConcretePolicy : public BASE } \ output += y; -//! \class AdditiveCipherTemplate -//! \brief Base class for additive stream ciphers with SymmetricCipher interface -//! \tparam BASE AbstractPolicyHolder base class +/// \class AdditiveCipherTemplate +/// \brief Base class for additive stream ciphers with SymmetricCipher interface +/// \tparam BASE AbstractPolicyHolder base class template > class CRYPTOPP_NO_VTABLE AdditiveCipherTemplate : public BASE, public RandomNumberGenerator { public: virtual ~AdditiveCipherTemplate() {} - //! \brief Generate random array of bytes - //! \param output the byte buffer - //! \param size the length of the buffer, in bytes - //! \details All generated values are uniformly distributed over the range specified within the - //! the constraints of a particular generator. + /// \brief Generate random array of bytes + /// \param output the byte buffer + /// \param size the length of the buffer, in bytes + /// \details All generated values are uniformly distributed over the range specified within the + /// the constraints of a particular generator. void GenerateBlock(byte *output, size_t size); - //! \brief Apply keystream to data - //! \param outString a buffer to write the transformed data - //! \param inString a buffer to read the data - //! \param length the size fo the buffers, in bytes - //! \details This is the primary method to operate a stream cipher. For example: - //! 
-	//!     size_t size = 30;
-	//!     byte plain[size] = "Do or do not; there is no try";
-	//!     byte cipher[size];
-	//!     ...
-	//!     ChaCha20 chacha(key, keySize);
-	//!     chacha.ProcessData(cipher, plain, size);
-	//!
+ /// \brief Apply keystream to data + /// \param outString a buffer to write the transformed data + /// \param inString a buffer to read the data + /// \param length the size fo the buffers, in bytes + /// \details This is the primary method to operate a stream cipher. For example: + /// 
+	///     size_t size = 30;
+	///     byte plain[size] = "Do or do not; there is no try";
+	///     byte cipher[size];
+	///     ...
+	///     ChaCha20 chacha(key, keySize);
+	///     chacha.ProcessData(cipher, plain, size);
+	///
void ProcessData(byte *outString, const byte *inString, size_t length); - //! \brief Resynchronize the cipher - //! \param iv a byte array used to resynchronize the cipher - //! \param length the size of the IV array + /// \brief Resynchronize the cipher + /// \param iv a byte array used to resynchronize the cipher + /// \param length the size of the IV array void Resynchronize(const byte *iv, int length=-1); - //! \brief Provides number of ideal bytes to process - //! \returns the ideal number of bytes to process - //! \details Internally, the default implementation returns GetBytesPerIteration() - //! \sa GetBytesPerIteration() and GetOptimalNextBlockSize() + /// \brief Provides number of ideal bytes to process + /// \returns the ideal number of bytes to process + /// \details Internally, the default implementation returns GetBytesPerIteration() + /// \sa GetBytesPerIteration() and GetOptimalNextBlockSize() unsigned int OptimalBlockSize() const {return this->GetPolicy().GetOptimalBlockSize();} - //! \brief Provides number of ideal bytes to process - //! \returns the ideal number of bytes to process - //! \details Internally, the default implementation returns remaining unprocessed bytes - //! \sa GetBytesPerIteration() and OptimalBlockSize() + /// \brief Provides number of ideal bytes to process + /// \returns the ideal number of bytes to process + /// \details Internally, the default implementation returns remaining unprocessed bytes + /// \sa GetBytesPerIteration() and OptimalBlockSize() unsigned int GetOptimalNextBlockSize() const {return (unsigned int)this->m_leftOver;} - //! \brief Provides number of ideal data alignment - //! \returns the ideal data alignment, in bytes - //! \sa GetAlignment() and OptimalBlockSize() + /// \brief Provides number of ideal data alignment + /// \returns the ideal data alignment, in bytes + /// \sa GetAlignment() and OptimalBlockSize() unsigned int OptimalDataAlignment() const {return this->GetPolicy().GetAlignment();} - //! \brief Determines if the cipher is self inverting - //! \returns true if the stream cipher is self inverting, false otherwise + /// \brief Determines if the cipher is self inverting + /// \returns true if the stream cipher is self inverting, false otherwise bool IsSelfInverting() const {return true;} - //! \brief Determines if the cipher is a forward transformation - //! \returns true if the stream cipher is a forward transformation, false otherwise + /// \brief Determines if the cipher is a forward transformation + /// \returns true if the stream cipher is a forward transformation, false otherwise bool IsForwardTransformation() const {return true;} - //! \brief Flag indicating random access - //! \returns true if the cipher is seekable, false otherwise - //! \sa Seek() + /// \brief Flag indicating random access + /// \returns true if the cipher is seekable, false otherwise + /// \sa Seek() bool IsRandomAccess() const {return this->GetPolicy().CipherIsRandomAccess();} - //! \brief Seeks to a random position in the stream - //! \param position the absolute position in the stream - //! \sa IsRandomAccess() + /// \brief Seeks to a random position in the stream + /// \param position the absolute position in the stream + /// \sa IsRandomAccess() void Seek(lword position); typedef typename BASE::PolicyInterface PolicyInterface; @@ -344,100 +344,100 @@ protected: size_t m_leftOver; }; -//! \class CFB_CipherAbstractPolicy -//! \brief Policy object for feeback based stream ciphers +/// \class CFB_CipherAbstractPolicy +/// \brief Policy object for feeback based stream ciphers class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CFB_CipherAbstractPolicy { public: virtual ~CFB_CipherAbstractPolicy() {} - //! \brief Provides data alignment requirements - //! \returns data alignment requirements, in bytes - //! \details Internally, the default implementation returns 1. If the stream cipher is implemented - //! using an SSE2 ASM or intrinsics, then the value returned is usually 16. + /// \brief Provides data alignment requirements + /// \returns data alignment requirements, in bytes + /// \details Internally, the default implementation returns 1. If the stream cipher is implemented + /// using an SSE2 ASM or intrinsics, then the value returned is usually 16. virtual unsigned int GetAlignment() const =0; - //! \brief Provides number of bytes operated upon during an iteration - //! \returns bytes operated upon during an iteration, in bytes - //! \sa GetOptimalBlockSize() + /// \brief Provides number of bytes operated upon during an iteration + /// \returns bytes operated upon during an iteration, in bytes + /// \sa GetOptimalBlockSize() virtual unsigned int GetBytesPerIteration() const =0; - //! \brief Access the feedback register - //! \returns pointer to the first byte of the feedback register + /// \brief Access the feedback register + /// \returns pointer to the first byte of the feedback register virtual byte * GetRegisterBegin() =0; - //! \brief TODO + /// \brief TODO virtual void TransformRegister() =0; - //! \brief Flag indicating iteration support - //! \returns true if the cipher supports iteration, false otherwise + /// \brief Flag indicating iteration support + /// \returns true if the cipher supports iteration, false otherwise virtual bool CanIterate() const {return false;} - //! \brief Iterate the cipher - //! \param output the output buffer - //! \param input the input buffer - //! \param dir the direction of the cipher - //! \param iterationCount the number of iterations to perform on the input - //! \sa IsSelfInverting() and IsForwardTransformation() + /// \brief Iterate the cipher + /// \param output the output buffer + /// \param input the input buffer + /// \param dir the direction of the cipher + /// \param iterationCount the number of iterations to perform on the input + /// \sa IsSelfInverting() and IsForwardTransformation() virtual void Iterate(byte *output, const byte *input, CipherDir dir, size_t iterationCount) {CRYPTOPP_UNUSED(output); CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(dir); CRYPTOPP_UNUSED(iterationCount); CRYPTOPP_ASSERT(false); /*throw 0;*/ throw Exception(Exception::OTHER_ERROR, "SimpleKeyingInterface: unexpected error");} - //! \brief Key the cipher - //! \param params set of NameValuePairs use to initialize this object - //! \param key a byte array used to key the cipher - //! \param length the size of the key array + /// \brief Key the cipher + /// \param params set of NameValuePairs use to initialize this object + /// \param key a byte array used to key the cipher + /// \param length the size of the key array virtual void CipherSetKey(const NameValuePairs ¶ms, const byte *key, size_t length) =0; - //! \brief Resynchronize the cipher - //! \param iv a byte array used to resynchronize the cipher - //! \param length the size of the IV array + /// \brief Resynchronize the cipher + /// \param iv a byte array used to resynchronize the cipher + /// \param length the size of the IV array virtual void CipherResynchronize(const byte *iv, size_t length) {CRYPTOPP_UNUSED(iv); CRYPTOPP_UNUSED(length); throw NotImplemented("SimpleKeyingInterface: this object doesn't support resynchronization");} }; -//! \class CFB_CipherConcretePolicy -//! \brief Base class for feedback based stream ciphers -//! \tparam WT word type -//! \tparam W count of words -//! \tparam BASE CFB_CipherAbstractPolicy derived base class +/// \class CFB_CipherConcretePolicy +/// \brief Base class for feedback based stream ciphers +/// \tparam WT word type +/// \tparam W count of words +/// \tparam BASE CFB_CipherAbstractPolicy derived base class template struct CRYPTOPP_NO_VTABLE CFB_CipherConcretePolicy : public BASE { typedef WT WordType; - //! \brief Provides data alignment requirements - //! \returns data alignment requirements, in bytes - //! \details Internally, the default implementation returns 1. If the stream cipher is implemented - //! using an SSE2 ASM or intrinsics, then the value returned is usually 16. + /// \brief Provides data alignment requirements + /// \returns data alignment requirements, in bytes + /// \details Internally, the default implementation returns 1. If the stream cipher is implemented + /// using an SSE2 ASM or intrinsics, then the value returned is usually 16. unsigned int GetAlignment() const {return sizeof(WordType);} - //! \brief Provides number of bytes operated upon during an iteration - //! \returns bytes operated upon during an iteration, in bytes - //! \sa GetOptimalBlockSize() + /// \brief Provides number of bytes operated upon during an iteration + /// \returns bytes operated upon during an iteration, in bytes + /// \sa GetOptimalBlockSize() unsigned int GetBytesPerIteration() const {return sizeof(WordType) * W;} - //! \brief Flag indicating iteration support - //! \returns true if the cipher supports iteration, false otherwise + /// \brief Flag indicating iteration support + /// \returns true if the cipher supports iteration, false otherwise bool CanIterate() const {return true;} - //! \brief Perform one iteration in the forward direction + /// \brief Perform one iteration in the forward direction void TransformRegister() {this->Iterate(NULLPTR, NULLPTR, ENCRYPTION, 1);} - //! \brief Provides alternate access to a feedback register - //! \tparam B enumeration indicating endianness - //! \details RegisterOutput() provides alternate access to the feedback register. The - //! enumeration B is BigEndian or LittleEndian. Repeatedly applying operator() - //! results in advancing in the register. + /// \brief Provides alternate access to a feedback register + /// \tparam B enumeration indicating endianness + /// \details RegisterOutput() provides alternate access to the feedback register. The + /// enumeration B is BigEndian or LittleEndian. Repeatedly applying operator() + /// results in advancing in the register. template struct RegisterOutput { RegisterOutput(byte *output, const byte *input, CipherDir dir) : m_output(output), m_input(input), m_dir(dir) {} - //! \brief XOR feedback register with data - //! \param registerWord data represented as a word type - //! \returns reference to the next feedback register word + /// \brief XOR feedback register with data + /// \param registerWord data represented as a word type + /// \returns reference to the next feedback register word inline RegisterOutput& operator()(WordType ®isterWord) { CRYPTOPP_ASSERT(IsAligned(m_output)); @@ -481,57 +481,57 @@ struct CRYPTOPP_NO_VTABLE CFB_CipherConcretePolicy : public BASE }; }; -//! \class CFB_CipherTemplate -//! \brief Base class for feedback based stream ciphers with SymmetricCipher interface -//! \tparam BASE AbstractPolicyHolder base class +/// \class CFB_CipherTemplate +/// \brief Base class for feedback based stream ciphers with SymmetricCipher interface +/// \tparam BASE AbstractPolicyHolder base class template class CRYPTOPP_NO_VTABLE CFB_CipherTemplate : public BASE { public: - //! \brief Apply keystream to data - //! \param outString a buffer to write the transformed data - //! \param inString a buffer to read the data - //! \param length the size fo the buffers, in bytes - //! \details This is the primary method to operate a stream cipher. For example: - //! 
-	//!     size_t size = 30;
-	//!     byte plain[size] = "Do or do not; there is no try";
-	//!     byte cipher[size];
-	//!     ...
-	//!     ChaCha20 chacha(key, keySize);
-	//!     chacha.ProcessData(cipher, plain, size);
-	//!
+ /// \brief Apply keystream to data + /// \param outString a buffer to write the transformed data + /// \param inString a buffer to read the data + /// \param length the size fo the buffers, in bytes + /// \details This is the primary method to operate a stream cipher. For example: + /// 
+	///     size_t size = 30;
+	///     byte plain[size] = "Do or do not; there is no try";
+	///     byte cipher[size];
+	///     ...
+	///     ChaCha20 chacha(key, keySize);
+	///     chacha.ProcessData(cipher, plain, size);
+	///
void ProcessData(byte *outString, const byte *inString, size_t length); - //! \brief Resynchronize the cipher - //! \param iv a byte array used to resynchronize the cipher - //! \param length the size of the IV array + /// \brief Resynchronize the cipher + /// \param iv a byte array used to resynchronize the cipher + /// \param length the size of the IV array void Resynchronize(const byte *iv, int length=-1); - //! \brief Provides number of ideal bytes to process - //! \returns the ideal number of bytes to process - //! \details Internally, the default implementation returns GetBytesPerIteration() - //! \sa GetBytesPerIteration() and GetOptimalNextBlockSize() + /// \brief Provides number of ideal bytes to process + /// \returns the ideal number of bytes to process + /// \details Internally, the default implementation returns GetBytesPerIteration() + /// \sa GetBytesPerIteration() and GetOptimalNextBlockSize() unsigned int OptimalBlockSize() const {return this->GetPolicy().GetBytesPerIteration();} - //! \brief Provides number of ideal bytes to process - //! \returns the ideal number of bytes to process - //! \details Internally, the default implementation returns remaining unprocessed bytes - //! \sa GetBytesPerIteration() and OptimalBlockSize() + /// \brief Provides number of ideal bytes to process + /// \returns the ideal number of bytes to process + /// \details Internally, the default implementation returns remaining unprocessed bytes + /// \sa GetBytesPerIteration() and OptimalBlockSize() unsigned int GetOptimalNextBlockSize() const {return (unsigned int)m_leftOver;} - //! \brief Provides number of ideal data alignment - //! \returns the ideal data alignment, in bytes - //! \sa GetAlignment() and OptimalBlockSize() + /// \brief Provides number of ideal data alignment + /// \returns the ideal data alignment, in bytes + /// \sa GetAlignment() and OptimalBlockSize() unsigned int OptimalDataAlignment() const {return this->GetPolicy().GetAlignment();} - //! \brief Flag indicating random access - //! \returns true if the cipher is seekable, false otherwise - //! \sa Seek() + /// \brief Flag indicating random access + /// \returns true if the cipher is seekable, false otherwise + /// \sa Seek() bool IsRandomAccess() const {return false;} - //! \brief Determines if the cipher is self inverting - //! \returns true if the stream cipher is self inverting, false otherwise + /// \brief Determines if the cipher is self inverting + /// \returns true if the stream cipher is self inverting, false otherwise bool IsSelfInverting() const {return false;} typedef typename BASE::PolicyInterface PolicyInterface; @@ -544,9 +544,9 @@ protected: size_t m_leftOver; }; -//! \class CFB_EncryptionTemplate -//! \brief Base class for feedback based stream ciphers in the forward direction with SymmetricCipher interface -//! \tparam BASE AbstractPolicyHolder base class +/// \class CFB_EncryptionTemplate +/// \brief Base class for feedback based stream ciphers in the forward direction with SymmetricCipher interface +/// \tparam BASE AbstractPolicyHolder base class template > class CRYPTOPP_NO_VTABLE CFB_EncryptionTemplate : public CFB_CipherTemplate { @@ -554,9 +554,9 @@ class CRYPTOPP_NO_VTABLE CFB_EncryptionTemplate : public CFB_CipherTemplate > class CRYPTOPP_NO_VTABLE CFB_DecryptionTemplate : public CFB_CipherTemplate { @@ -564,9 +564,9 @@ class CRYPTOPP_NO_VTABLE CFB_DecryptionTemplate : public CFB_CipherTemplate class CFB_RequireFullDataBlocks : public BASE { @@ -574,41 +574,41 @@ public: unsigned int MandatoryBlockSize() const {return this->OptimalBlockSize();} }; -//! \class SymmetricCipherFinal -//! \brief SymmetricCipher implementation -//! \tparam BASE AbstractPolicyHolder derived base class -//! \tparam INFO AbstractPolicyHolder derived information class -//! \sa Weak::ARC4, ChaCha8, ChaCha12, ChaCha20, Salsa20, SEAL, Sosemanuk, WAKE +/// \class SymmetricCipherFinal +/// \brief SymmetricCipher implementation +/// \tparam BASE AbstractPolicyHolder derived base class +/// \tparam INFO AbstractPolicyHolder derived information class +/// \sa Weak::ARC4, ChaCha8, ChaCha12, ChaCha20, Salsa20, SEAL, Sosemanuk, WAKE template class SymmetricCipherFinal : public AlgorithmImpl, INFO> { public: virtual ~SymmetricCipherFinal() {} - //! \brief Construct a stream cipher + /// \brief Construct a stream cipher SymmetricCipherFinal() {} - //! \brief Construct a stream cipher - //! \param key a byte array used to key the cipher - //! \details This overload uses DEFAULT_KEYLENGTH + /// \brief Construct a stream cipher + /// \param key a byte array used to key the cipher + /// \details This overload uses DEFAULT_KEYLENGTH SymmetricCipherFinal(const byte *key) {this->SetKey(key, this->DEFAULT_KEYLENGTH);} - //! \brief Construct a stream cipher - //! \param key a byte array used to key the cipher - //! \param length the size of the key array + /// \brief Construct a stream cipher + /// \param key a byte array used to key the cipher + /// \param length the size of the key array SymmetricCipherFinal(const byte *key, size_t length) {this->SetKey(key, length);} - //! \brief Construct a stream cipher - //! \param key a byte array used to key the cipher - //! \param length the size of the key array - //! \param iv a byte array used as an initialization vector + /// \brief Construct a stream cipher + /// \param key a byte array used to key the cipher + /// \param length the size of the key array + /// \param iv a byte array used as an initialization vector SymmetricCipherFinal(const byte *key, size_t length, const byte *iv) {this->SetKeyWithIV(key, length, iv);} - //! \brief Clone a SymmetricCipher - //! \returns a new SymmetricCipher based on this object + /// \brief Clone a SymmetricCipher + /// \returns a new SymmetricCipher based on this object Clonable * Clone() const {return static_cast(new SymmetricCipherFinal(*this));} }; diff --git a/tea.h b/tea.h index 966b78b9..ba1ad50e 100644 --- a/tea.h +++ b/tea.h @@ -1,7 +1,7 @@ // tea.h - originally written and placed in the public domain by Wei Dai -//! \file tea.h -//! \brief Classes for the TEA, BTEA and XTEA block ciphers +/// \file tea.h +/// \brief Classes for the TEA, BTEA and XTEA block ciphers #ifndef CRYPTOPP_TEA_H #define CRYPTOPP_TEA_H @@ -12,20 +12,20 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class TEA_Info -//! \brief TEA block cipher information +/// \class TEA_Info +/// \brief TEA block cipher information struct TEA_Info : public FixedBlockSize<8>, public FixedKeyLength<16>, public VariableRounds<32> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "TEA";} }; -//! \class TEA -//! \brief TEA block cipher -//! \sa TEA +/// \class TEA +/// \brief TEA block cipher +/// \sa TEA class TEA : public TEA_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief TEA block cipher default operation + /// \class Base + /// \brief TEA block cipher default operation class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -36,16 +36,16 @@ class TEA : public TEA_Info, public BlockCipherDocumentation word32 m_limit; }; - //! \class Enc - //! \brief TEA block cipher encryption operation + /// \class Enc + /// \brief TEA block cipher encryption operation class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \class Dec - //! \brief TEA block cipher decryption operation + /// \class Dec + /// \brief TEA block cipher decryption operation class CRYPTOPP_NO_VTABLE Dec : public Base { public: @@ -60,20 +60,20 @@ public: typedef TEA::Encryption TEAEncryption; typedef TEA::Decryption TEADecryption; -//! \class XTEA_Info -//! \brief XTEA block cipher information +/// \class XTEA_Info +/// \brief XTEA block cipher information struct XTEA_Info : public FixedBlockSize<8>, public FixedKeyLength<16>, public VariableRounds<32> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "XTEA";} }; -//! \class XTEA -//! \brief XTEA block cipher -//! \sa XTEA +/// \class XTEA +/// \brief XTEA block cipher +/// \sa XTEA class XTEA : public XTEA_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief XTEA block cipher default operation + /// \class Base + /// \brief XTEA block cipher default operation class CRYPTOPP_NO_VTABLE Base : public BlockCipherImpl { public: @@ -84,16 +84,16 @@ class XTEA : public XTEA_Info, public BlockCipherDocumentation word32 m_limit; }; - //! \class Enc - //! \brief XTEA block cipher encryption operation + /// \class Enc + /// \brief XTEA block cipher encryption operation class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \class Dec - //! \brief XTEA block cipher decryption operation + /// \class Dec + /// \brief XTEA block cipher decryption operation class CRYPTOPP_NO_VTABLE Dec : public Base { public: @@ -105,21 +105,21 @@ public: typedef BlockCipherFinal Decryption; }; -//! \class BTEA_Info -//! \brief BTEA block cipher information +/// \class BTEA_Info +/// \brief BTEA block cipher information struct BTEA_Info : public FixedKeyLength<16> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "BTEA";} }; -//! \class BTEA -//! \brief BTEA block cipher -//! \details Corrected Block TEA as described in "xxtea". This class hasn't been tested yet. -//! \sa Corrected Block TEA. +/// \class BTEA +/// \brief BTEA block cipher +/// \details Corrected Block TEA as described in "xxtea". This class hasn't been tested yet. +/// \sa Corrected Block TEA. class BTEA : public BTEA_Info, public BlockCipherDocumentation { - //! \class Base - //! \brief BTEA block cipher default operation + /// \class Base + /// \brief BTEA block cipher default operation class CRYPTOPP_NO_VTABLE Base : public AlgorithmImpl, BTEA_Info>, public BTEA_Info { public: @@ -137,16 +137,16 @@ class BTEA : public BTEA_Info, public BlockCipherDocumentation unsigned int m_blockSize; }; - //! \class Enc - //! \brief BTEA block cipher encryption operation + /// \class Enc + /// \brief BTEA block cipher encryption operation class CRYPTOPP_NO_VTABLE Enc : public Base { public: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \class Dec - //! \brief BTEA block cipher decryption operation + /// \class Dec + /// \brief BTEA block cipher decryption operation class CRYPTOPP_NO_VTABLE Dec : public Base { public: diff --git a/threefish.h b/threefish.h index 1d212c5a..c1e5672e 100644 --- a/threefish.h +++ b/threefish.h @@ -2,9 +2,9 @@ // Based on public domain code by Keru Kuro. Kuro's code is // available at http://cppcrypto.sourceforge.net/. -//! \file Threefish.h -//! \brief Classes for the Threefish block cipher -//! \since Crypto++ 6.0 +/// \file Threefish.h +/// \brief Classes for the Threefish block cipher +/// \since Crypto++ 6.0 #ifndef CRYPTOPP_THREEFISH_H #define CRYPTOPP_THREEFISH_H @@ -18,10 +18,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Threefish_Info -//! \brief Threefish block cipher information -//! \tparam BS block size of the cipher, in bytes -//! \since Crypto++ 6.0 +/// \class Threefish_Info +/// \brief Threefish block cipher information +/// \tparam BS block size of the cipher, in bytes +/// \since Crypto++ 6.0 template struct Threefish_Info : public FixedBlockSize, FixedKeyLength { @@ -32,12 +32,12 @@ struct Threefish_Info : public FixedBlockSize, FixedKeyLength } }; -//! \class Threefish_Base -//! \brief Threefish block cipher base class -//! \tparam BS block size of the cipher, in bytes -//! \details User code should use Threefish256, Threefish512, Threefish1024 -//! \sa Threefish256, Threefish512, Threefish1024, Threefish -//! \since Crypto++ 6.0 +/// \class Threefish_Base +/// \brief Threefish block cipher base class +/// \tparam BS block size of the cipher, in bytes +/// \details User code should use Threefish256, Threefish512, Threefish1024 +/// \sa Threefish256, Threefish512, Threefish1024, Threefish +/// \since Crypto++ 6.0 template struct CRYPTOPP_NO_VTABLE Threefish_Base { @@ -66,38 +66,38 @@ struct CRYPTOPP_NO_VTABLE Threefish_Base AlignedSecBlock64 m_tweak; }; -//! \class Threefish256 -//! \brief Threefish 256-bit block cipher -//! \details Threefish256 provides 256-bit block size. The valid key size is 256-bit. -//! \note Crypto++ provides a byte oriented implementation -//! \sa Threefish256, Threefish512, Threefish1024, Threefish -//! \since Crypto++ 6.0 +/// \class Threefish256 +/// \brief Threefish 256-bit block cipher +/// \details Threefish256 provides 256-bit block size. The valid key size is 256-bit. +/// \note Crypto++ provides a byte oriented implementation +/// \sa Threefish256, Threefish512, Threefish1024, Threefish +/// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Threefish256 : public Threefish_Info<32>, public BlockCipherDocumentation { public: - //! \brief Threefish block cipher transformation functions - //! \details Provides implementation common to encryption and decryption - //! \since Crypto++ 6.0 + /// \brief Threefish block cipher transformation functions + /// \details Provides implementation common to encryption and decryption + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Base : public Threefish_Base<32>, public BlockCipherImpl > { protected: void UncheckedSetKey(const byte *userKey, unsigned int keyLength, const NameValuePairs ¶ms); }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key and block - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key and block + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Enc : public Base { protected: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \brief Provides implementation for encryption transformation - //! \details Dec provides implementation for decryption transformation. All key and block - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Dec provides implementation for decryption transformation. All key and block + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Dec : public Base { protected: @@ -111,38 +111,38 @@ public: typedef Threefish256::Encryption Threefish256Encryption; typedef Threefish256::Decryption Threefish256Decryption; -//! \class Threefish512 -//! \brief Threefish 512-bit block cipher -//! \details Threefish512 provides 512-bit block size. The valid key size is 512-bit. -//! \note Crypto++ provides a byte oriented implementation -//! \sa Threefish256, Threefish512, Threefish1024, Threefish -//! \since Crypto++ 6.0 +/// \class Threefish512 +/// \brief Threefish 512-bit block cipher +/// \details Threefish512 provides 512-bit block size. The valid key size is 512-bit. +/// \note Crypto++ provides a byte oriented implementation +/// \sa Threefish256, Threefish512, Threefish1024, Threefish +/// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Threefish512 : public Threefish_Base<32>, public BlockCipherDocumentation { public: - //! \brief Threefish block cipher transformation functions - //! \details Provides implementation common to encryption and decryption - //! \since Crypto++ 6.0 + /// \brief Threefish block cipher transformation functions + /// \details Provides implementation common to encryption and decryption + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Base : public Threefish_Base<64>, public BlockCipherImpl > { protected: void UncheckedSetKey(const byte *userKey, unsigned int keyLength, const NameValuePairs ¶ms); }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key and block - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key and block + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Enc : public Base { protected: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \brief Provides implementation for encryption transformation - //! \details Dec provides implementation for decryption transformation. All key and block - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Dec provides implementation for decryption transformation. All key and block + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Dec : public Base { protected: @@ -156,38 +156,38 @@ public: typedef Threefish512::Encryption Threefish512Encryption; typedef Threefish512::Decryption Threefish512Decryption; -//! \class Threefish1024 -//! \brief Threefish 1024-bit block cipher -//! \details Threefish1024 provides 1024-bit block size. The valid key size is 1024-bit. -//! \note Crypto++ provides a byte oriented implementation -//! \sa Threefish256, Threefish512, Threefish1024, Threefish -//! \since Crypto++ 6.0 +/// \class Threefish1024 +/// \brief Threefish 1024-bit block cipher +/// \details Threefish1024 provides 1024-bit block size. The valid key size is 1024-bit. +/// \note Crypto++ provides a byte oriented implementation +/// \sa Threefish256, Threefish512, Threefish1024, Threefish +/// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Threefish1024 : public Threefish_Base<32>, public BlockCipherDocumentation { public: - //! \brief Threefish block cipher transformation functions - //! \details Provides implementation common to encryption and decryption - //! \since Crypto++ 6.0 + /// \brief Threefish block cipher transformation functions + /// \details Provides implementation common to encryption and decryption + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Base : public Threefish_Base<128>, public BlockCipherImpl > { protected: void UncheckedSetKey(const byte *userKey, unsigned int keyLength, const NameValuePairs ¶ms); }; - //! \brief Provides implementation for encryption transformation - //! \details Enc provides implementation for encryption transformation. All key and block - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Enc provides implementation for encryption transformation. All key and block + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Enc : public Base { protected: void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const; }; - //! \brief Provides implementation for encryption transformation - //! \details Dec provides implementation for decryption transformation. All key and block - //! sizes are supported. - //! \since Crypto++ 6.0 + /// \brief Provides implementation for encryption transformation + /// \details Dec provides implementation for decryption transformation. All key and block + /// sizes are supported. + /// \since Crypto++ 6.0 class CRYPTOPP_NO_VTABLE Dec : public Base { protected: diff --git a/trap.h b/trap.h index 0508447d..f30ba293 100644 --- a/trap.h +++ b/trap.h @@ -1,16 +1,16 @@ // trap.h - written and placed in public domain by Jeffrey Walton. -//! \file trap.h -//! \brief Debugging and diagnostic assertions -//! \details CRYPTOPP_ASSERT is the library's debugging and diagnostic assertion. CRYPTOPP_ASSERT -//! is enabled by CRYPTOPP_DEBUG, DEBUG or _DEBUG. -//! \details CRYPTOPP_ASSERT raises a SIGTRAP (Unix) or calls __debugbreak() (Windows). -//! CRYPTOPP_ASSERT is only in effect when the user requests a debug configuration. Unlike Posix assert, -//! NDEBUG (or failure to define it) does not affect the library. -//! The traditional Posix define NDEBUG has no effect on CRYPTOPP_DEBUG or DebugTrapHandler. -//! \since Crypto++ 5.6.5 -//! \sa DebugTrapHandler, Issue 277, -//! CVE-2016-7420 +/// \file trap.h +/// \brief Debugging and diagnostic assertions +/// \details CRYPTOPP_ASSERT is the library's debugging and diagnostic assertion. CRYPTOPP_ASSERT +/// is enabled by CRYPTOPP_DEBUG, DEBUG or _DEBUG. +/// \details CRYPTOPP_ASSERT raises a SIGTRAP (Unix) or calls __debugbreak() (Windows). +/// CRYPTOPP_ASSERT is only in effect when the user requests a debug configuration. Unlike Posix assert, +/// NDEBUG (or failure to define it) does not affect the library. +/// The traditional Posix define NDEBUG has no effect on CRYPTOPP_DEBUG or DebugTrapHandler. +/// \since Crypto++ 5.6.5 +/// \sa DebugTrapHandler, Issue 277, +/// CVE-2016-7420 #ifndef CRYPTOPP_TRAP_H #define CRYPTOPP_TRAP_H @@ -31,32 +31,32 @@ // ************** run-time assertion *************** #if defined(CRYPTOPP_DOXYGEN_PROCESSING) -//! \brief Debugging and diagnostic assertion -//! \details CRYPTOPP_ASSERT is the library's debugging and diagnostic assertion. CRYPTOPP_ASSERT -//! is enabled by the preprocessor macros CRYPTOPP_DEBUG, DEBUG or _DEBUG. -//! \details CRYPTOPP_ASSERT raises a SIGTRAP (Unix) or calls DebugBreak() (Windows). -//! CRYPTOPP_ASSERT is only in effect when the user explicitly requests a debug configuration. -//! \details If you want to ensure CRYPTOPP_ASSERT is inert, then do not define -//! CRYPTOPP_DEBUG, DEBUG or _DEBUG. Avoiding the defines means CRYPTOPP_ASSERT -//! is preprocessed into an empty string. -//! \details The traditional Posix define NDEBUG has no effect on CRYPTOPP_DEBUG, CRYPTOPP_ASSERT -//! or DebugTrapHandler. -//! \details An example of using \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT" and DebugTrapHandler is shown below. The library's -//! test program, cryptest.exe (from test.cpp), exercises the structure: -//! 
-//!    #if defined(CRYPTOPP_DEBUG) && defined(UNIX_SIGNALS_AVAILABLE)
-//!    static const DebugTrapHandler g_dummyHandler;
-//!    #endif
-//!
-//!    int main(int argc, char* argv[])
-//!    {
-//!       CRYPTOPP_ASSERT(argv != nullptr);
-//!       ...
-//!    }
-//!
-//! \since Crypto++ 5.6.5 -//! \sa DebugTrapHandler, SignalHandler, Issue 277, -//! CVE-2016-7420 +/// \brief Debugging and diagnostic assertion +/// \details CRYPTOPP_ASSERT is the library's debugging and diagnostic assertion. CRYPTOPP_ASSERT +/// is enabled by the preprocessor macros CRYPTOPP_DEBUG, DEBUG or _DEBUG. +/// \details CRYPTOPP_ASSERT raises a SIGTRAP (Unix) or calls DebugBreak() (Windows). +/// CRYPTOPP_ASSERT is only in effect when the user explicitly requests a debug configuration. +/// \details If you want to ensure CRYPTOPP_ASSERT is inert, then do not define +/// CRYPTOPP_DEBUG, DEBUG or _DEBUG. Avoiding the defines means CRYPTOPP_ASSERT +/// is preprocessed into an empty string. +/// \details The traditional Posix define NDEBUG has no effect on CRYPTOPP_DEBUG, CRYPTOPP_ASSERT +/// or DebugTrapHandler. +/// \details An example of using \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT" and DebugTrapHandler is shown below. The library's +/// test program, cryptest.exe (from test.cpp), exercises the structure: +/// 
+///    #if defined(CRYPTOPP_DEBUG) && defined(UNIX_SIGNALS_AVAILABLE)
+///    static const DebugTrapHandler g_dummyHandler;
+///    #endif
+///
+///    int main(int argc, char* argv[])
+///    {
+///       CRYPTOPP_ASSERT(argv != nullptr);
+///       ...
+///    }
+///
+/// \since Crypto++ 5.6.5 +/// \sa DebugTrapHandler, SignalHandler, Issue 277, +/// CVE-2016-7420 # define CRYPTOPP_ASSERT(exp) { ... } #endif @@ -95,41 +95,41 @@ NAMESPACE_BEGIN(CryptoPP) // ************** SIGTRAP handler *************** #if (CRYPTOPP_DEBUG && defined(UNIX_SIGNALS_AVAILABLE)) || defined(CRYPTOPP_DOXYGEN_PROCESSING) -//! \brief Default SIGTRAP handler -//! \details DebugTrapHandler() can be used by a program to install an empty SIGTRAP handler. If present, -//! the handler ensures there is a signal handler in place for SIGTRAP raised by -//! CRYPTOPP_ASSERT. If CRYPTOPP_ASSERT raises SIGTRAP without -//! a handler, then one of two things can occur. First, the OS might allow the program -//! to continue. Second, the OS might terminate the program. OS X allows the program to continue, while -//! some Linuxes terminate the program. -//! \details If DebugTrapHandler detects another handler in place, then it will not install a handler. This -//! ensures a debugger can gain control of the SIGTRAP signal without contention. It also allows multiple -//! DebugTrapHandler to be created without contentious or unusual behavior. Though multiple DebugTrapHandler can be -//! created, a program should only create one, if needed. -//! \details A DebugTrapHandler is subject to C++ static initialization [dis]order. If you need to install a handler -//! and it must be installed early, then reference the code associated with CRYPTOPP_INIT_PRIORITY in -//! cryptlib.cpp and cpu.cpp. -//! \details If you want to ensure CRYPTOPP_ASSERT is inert, then do not define -//! CRYPTOPP_DEBUG, DEBUG or _DEBUG. Avoiding the defines means CRYPTOPP_ASSERT -//! is processed into ((void)(exp)). -//! \details The traditional Posix define NDEBUG has no effect on CRYPTOPP_DEBUG, CRYPTOPP_ASSERT -//! or DebugTrapHandler. -//! \details An example of using \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT" and DebugTrapHandler is shown below. The library's -//! test program, cryptest.exe (from test.cpp), exercises the structure: -//! 
-//!    #if defined(CRYPTOPP_DEBUG) && defined(UNIX_SIGNALS_AVAILABLE)
-//!    static const DebugTrapHandler g_dummyHandler;
-//!    #endif
-//!
-//!    int main(int argc, char* argv[])
-//!    {
-//!       CRYPTOPP_ASSERT(argv != nullptr);
-//!       ...
-//!    }
-//!
-//! \since Crypto++ 5.6.5 -//! \sa \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT", SignalHandler, Issue 277, -//! CVE-2016-7420 +/// \brief Default SIGTRAP handler +/// \details DebugTrapHandler() can be used by a program to install an empty SIGTRAP handler. If present, +/// the handler ensures there is a signal handler in place for SIGTRAP raised by +/// CRYPTOPP_ASSERT. If CRYPTOPP_ASSERT raises SIGTRAP without +/// a handler, then one of two things can occur. First, the OS might allow the program +/// to continue. Second, the OS might terminate the program. OS X allows the program to continue, while +/// some Linuxes terminate the program. +/// \details If DebugTrapHandler detects another handler in place, then it will not install a handler. This +/// ensures a debugger can gain control of the SIGTRAP signal without contention. It also allows multiple +/// DebugTrapHandler to be created without contentious or unusual behavior. Though multiple DebugTrapHandler can be +/// created, a program should only create one, if needed. +/// \details A DebugTrapHandler is subject to C++ static initialization [dis]order. If you need to install a handler +/// and it must be installed early, then reference the code associated with CRYPTOPP_INIT_PRIORITY in +/// cryptlib.cpp and cpu.cpp. +/// \details If you want to ensure CRYPTOPP_ASSERT is inert, then do not define +/// CRYPTOPP_DEBUG, DEBUG or _DEBUG. Avoiding the defines means CRYPTOPP_ASSERT +/// is processed into ((void)(exp)). +/// \details The traditional Posix define NDEBUG has no effect on CRYPTOPP_DEBUG, CRYPTOPP_ASSERT +/// or DebugTrapHandler. +/// \details An example of using \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT" and DebugTrapHandler is shown below. The library's +/// test program, cryptest.exe (from test.cpp), exercises the structure: +/// 
+///    #if defined(CRYPTOPP_DEBUG) && defined(UNIX_SIGNALS_AVAILABLE)
+///    static const DebugTrapHandler g_dummyHandler;
+///    #endif
+///
+///    int main(int argc, char* argv[])
+///    {
+///       CRYPTOPP_ASSERT(argv != nullptr);
+///       ...
+///    }
+///
+/// \since Crypto++ 5.6.5 +/// \sa \ref CRYPTOPP_ASSERT "CRYPTOPP_ASSERT", SignalHandler, Issue 277, +/// CVE-2016-7420 #if defined(CRYPTOPP_DOXYGEN_PROCESSING) class DebugTrapHandler : public SignalHandler { }; diff --git a/trdlocal.h b/trdlocal.h index a3eb0431..a30ca692 100644 --- a/trdlocal.h +++ b/trdlocal.h @@ -16,11 +16,11 @@ typedef pthread_key_t ThreadLocalIndexType; NAMESPACE_BEGIN(CryptoPP) -//! thread local storage +/// thread local storage class CRYPTOPP_DLL ThreadLocalStorage : public NotCopyable { public: - //! exception thrown by ThreadLocalStorage class + /// exception thrown by ThreadLocalStorage class class Err : public OS_Error { public: diff --git a/trunhash.h b/trunhash.h index 7ca33b7c..38fc6675 100644 --- a/trunhash.h +++ b/trunhash.h @@ -18,7 +18,7 @@ public: {CRYPTOPP_UNUSED(digest);CRYPTOPP_UNUSED(digestLength);return true;} }; -//! construct new HashModule with smaller DigestSize() from existing one +/// construct new HashModule with smaller DigestSize() from existing one template class TruncatedHashTemplate : public HashTransformation { diff --git a/ttmac.h b/ttmac.h index 47b32ca2..d0943c80 100644 --- a/ttmac.h +++ b/ttmac.h @@ -1,7 +1,7 @@ // ttmac.h - written and placed in the public domain by Kevin Springle -//! \file ttmac.h -//! \brief Classes for the TTMAC message authentication code +/// \file ttmac.h +/// \brief Classes for the TTMAC message authentication code #ifndef CRYPTOPP_TTMAC_H #define CRYPTOPP_TTMAC_H @@ -12,8 +12,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class TTMAC_Base -//! \brief TTMAC message authentication code information +/// \class TTMAC_Base +/// \brief TTMAC message authentication code information class CRYPTOPP_NO_VTABLE TTMAC_Base : public FixedKeyLength<20>, public IteratedHash { public: @@ -34,11 +34,11 @@ protected: FixedSizeSecBlock m_key; }; -//! \class TTMAC -//! \brief Two-Track-MAC message authentication code -//! \tparam T HashTransformation class -//! \details 160-bit MAC with 160-bit key -//! \sa MessageAuthenticationCode(), Two-Track-MAC +/// \class TTMAC +/// \brief Two-Track-MAC message authentication code +/// \tparam T HashTransformation class +/// \details 160-bit MAC with 160-bit key +/// \sa MessageAuthenticationCode(), Two-Track-MAC DOCUMENTED_TYPEDEF(MessageAuthenticationCodeFinal, TTMAC) NAMESPACE_END diff --git a/twofish.h b/twofish.h index 388b4468..7dcf74a6 100644 --- a/twofish.h +++ b/twofish.h @@ -1,7 +1,7 @@ // twofish.h - originally written and placed in the public domain by Wei Dai -//! \file twofish.h -//! \brief Classes for the Twofish block cipher +/// \file twofish.h +/// \brief Classes for the Twofish block cipher #ifndef CRYPTOPP_TWOFISH_H #define CRYPTOPP_TWOFISH_H @@ -11,15 +11,15 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class Twofish_Info -//! \brief Twofish block cipher information +/// \class Twofish_Info +/// \brief Twofish block cipher information struct Twofish_Info : public FixedBlockSize<16>, public VariableKeyLength<16, 16, 32, 8>, FixedRounds<16> { CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() {return "Twofish";} }; -//! \class Twofish -//! \brief Twofish block cipher +/// \class Twofish +/// \brief Twofish block cipher //~ \sa Twofish class Twofish : public Twofish_Info, public BlockCipherDocumentation { diff --git a/vmac.h b/vmac.h index 535e2075..3e61bc43 100644 --- a/vmac.h +++ b/vmac.h @@ -1,8 +1,8 @@ // vmac.h - originally written and placed in the public domain by Wei Dai -//! \file vmac.h -//! \brief Classes for the VMAC message authentication code -//! \since Crypto++ 5.5 +/// \file vmac.h +/// \brief Classes for the VMAC message authentication code +/// \since Crypto++ 5.5 #ifndef CRYPTOPP_VMAC_H #define CRYPTOPP_VMAC_H @@ -19,9 +19,9 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class VMAC_Base -//! \brief VMAC message authentication code base class -//! \since Crypto++ 5.5 +/// \class VMAC_Base +/// \brief VMAC message authentication code base class +/// \since Crypto++ 5.5 class VMAC_Base : public IteratedHashBase { public: @@ -64,17 +64,17 @@ protected: unsigned int m_L1KeyLength; }; -//! \class VMAC -//! \brief VMAC message authentication code -//! \tparam T_BlockCipher block cipher -//! \tparam T_DigestBitSize digest size, in bits -//! \details VMAC is a block cipher-based message authentication code algorithm -//! using a universal hash proposed by Ted Krovetz and Wei Dai in April 2007. The -//! algorithm was designed for high performance backed by a formal analysis. -//! \details The implementation is based on Ted Krovetz's public domain vmac.c -//! and draft-krovetz-vmac-01.txt. -//! \sa VMAC. -//! \since Crypto++ 5.5 +/// \class VMAC +/// \brief VMAC message authentication code +/// \tparam T_BlockCipher block cipher +/// \tparam T_DigestBitSize digest size, in bits +/// \details VMAC is a block cipher-based message authentication code algorithm +/// using a universal hash proposed by Ted Krovetz and Wei Dai in April 2007. The +/// algorithm was designed for high performance backed by a formal analysis. +/// \details The implementation is based on Ted Krovetz's public domain vmac.c +/// and draft-krovetz-vmac-01.txt. +/// \sa VMAC. +/// \since Crypto++ 5.5 template class VMAC : public SimpleKeyingInterfaceImpl > { diff --git a/wait.h b/wait.h index c1cbddd5..0bd51049 100644 --- a/wait.h +++ b/wait.h @@ -48,7 +48,7 @@ public: virtual ~Tracer() {} protected: - //! Override this in your most-derived tracer to do the actual tracing. + /// Override this in your most-derived tracer to do the actual tracing. virtual void Trace(unsigned int n, std::string const& s) = 0; /*! By default, tracers will decide which trace messages to trace according to a trace level @@ -165,11 +165,11 @@ CRYPTOPP_END_TRACER_CLASS struct WaitingThreadData; -//! container of wait objects +/// container of wait objects class WaitObjectContainer : public NotCopyable { public: - //! exception thrown by WaitObjectContainer + /// exception thrown by WaitObjectContainer class Err : public Exception { public: diff --git a/wake.h b/wake.h index 81060801..8f1269e7 100644 --- a/wake.h +++ b/wake.h @@ -1,7 +1,7 @@ // wake.h - originally written and placed in the public domain by Wei Dai -//! \file wake.h -//! \brief Classes for WAKE stream cipher +/// \file wake.h +/// \brief Classes for WAKE stream cipher #ifndef CRYPTOPP_WAKE_H #define CRYPTOPP_WAKE_H @@ -12,10 +12,10 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class WAKE_OFB_Info -//! \brief WAKE stream cipher information -//! \tparam B Endianness of the stream cipher -//! \since Crypto++ 1.0 +/// \class WAKE_OFB_Info +/// \brief WAKE stream cipher information +/// \tparam B Endianness of the stream cipher +/// \since Crypto++ 1.0 template struct WAKE_OFB_Info : public FixedKeyLength<32> { @@ -32,10 +32,10 @@ protected: word32 r3, r4, r5, r6; }; -//! \class WAKE_Policy -//! \brief WAKE stream cipher operation -//! \tparam B Endianness of the stream cipher -//! \since Crypto++ 1.0 +/// \class WAKE_Policy +/// \brief WAKE stream cipher operation +/// \tparam B Endianness of the stream cipher +/// \since Crypto++ 1.0 template class CRYPTOPP_NO_VTABLE WAKE_Policy : public AdditiveCipherConcretePolicy, protected WAKE_Base { @@ -46,10 +46,10 @@ protected: bool CipherIsRandomAccess() const {return false;} }; -//! \class WAKE_OFB -//! \brief WAKE stream cipher -//! \tparam B Endianness of the stream cipher -//! \since Crypto++ 1.0 +/// \class WAKE_OFB +/// \brief WAKE stream cipher +/// \tparam B Endianness of the stream cipher +/// \since Crypto++ 1.0 template struct WAKE_OFB : public WAKE_OFB_Info, public SymmetricCipherDocumentation { diff --git a/whrlpool.h b/whrlpool.h index dd6a0742..3a32731f 100644 --- a/whrlpool.h +++ b/whrlpool.h @@ -6,7 +6,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! Whirlpool +/// Whirlpool class Whirlpool : public IteratedHashWithStaticTransform { public: diff --git a/winpipes.h b/winpipes.h index 61fabdf1..347e800c 100644 --- a/winpipes.h +++ b/winpipes.h @@ -12,7 +12,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! \brief Windows Handle +/// \brief Windows Handle class WindowsHandle { public: @@ -38,7 +38,7 @@ protected: bool m_own; }; -//! \brief Windows Pipe +/// \brief Windows Pipe class WindowsPipe { public: @@ -59,7 +59,7 @@ protected: {if (!result) HandleError(operation);} }; -//! \brief Pipe-based implementation of NetworkReceiver +/// \brief Pipe-based implementation of NetworkReceiver class WindowsPipeReceiver : public WindowsPipe, public NetworkReceiver { public: @@ -82,7 +82,7 @@ private: bool m_eofReceived; }; -//! \brief Pipe-based implementation of NetworkSender +/// \brief Pipe-based implementation of NetworkSender class WindowsPipeSender : public WindowsPipe, public NetworkSender { public: @@ -105,7 +105,7 @@ private: bool m_resultPending; }; -//! \brief Windows Pipe Source +/// \brief Windows Pipe Source class WindowsPipeSource : public WindowsHandle, public NetworkSource, public WindowsPipeReceiver { public: @@ -124,7 +124,7 @@ private: NetworkReceiver & AccessReceiver() {return *this;} }; -//! \brief Windows Pipe Sink +/// \brief Windows Pipe Sink class WindowsPipeSink : public WindowsHandle, public NetworkSink, public WindowsPipeSender { public: diff --git a/xtr.h b/xtr.h index 301d51cc..396c11e6 100644 --- a/xtr.h +++ b/xtr.h @@ -1,9 +1,9 @@ #ifndef CRYPTOPP_XTR_H #define CRYPTOPP_XTR_H -//! \file xtr.h -//! \brief The XTR public key system -//! \details The XTR public key system by Arjen K. Lenstra and Eric R. Verheul +/// \file xtr.h +/// \brief The XTR public key system +/// \details The XTR public key system by Arjen K. Lenstra and Eric R. Verheul #include "cryptlib.h" #include "modarith.h" @@ -12,8 +12,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class GFP2Element -//! \brief an element of GF(p^2) +/// \class GFP2Element +/// \brief an element of GF(p^2) class GFP2Element { public: @@ -42,8 +42,8 @@ public: Integer c1, c2; }; -//! \class GFP2_ONB -//! \brief GF(p^2), optimal normal basis +/// \class GFP2_ONB +/// \brief GF(p^2), optimal normal basis template class GFP2_ONB : public AbstractRing { @@ -211,7 +211,7 @@ protected: mutable Integer t; }; -//! \brief Creates primes p,q and generator g for XTR +/// \brief Creates primes p,q and generator g for XTR void XTR_FindPrimesAndGenerator(RandomNumberGenerator &rng, Integer &p, Integer &q, GFP2Element &g, unsigned int pbits, unsigned int qbits); GFP2Element XTR_Exponentiate(const GFP2Element &b, const Integer &e, const Integer &p); diff --git a/xtrcrypt.h b/xtrcrypt.h index cdbccdac..0edf93e2 100644 --- a/xtrcrypt.h +++ b/xtrcrypt.h @@ -11,7 +11,7 @@ NAMESPACE_BEGIN(CryptoPP) -//! XTR-DH with key validation +/// XTR-DH with key validation class XTR_DH : public SimpleKeyAgreementDomain, public CryptoParameters { diff --git a/zdeflate.h b/zdeflate.h index e9c51b1c..8b1d5cb6 100644 --- a/zdeflate.h +++ b/zdeflate.h @@ -1,7 +1,7 @@ // zdeflate.h - originally written and placed in the public domain by Wei Dai -//! \file zdeflate.h -//! \brief DEFLATE compression and decompression (RFC 1951) +/// \file zdeflate.h +/// \brief DEFLATE compression and decompression (RFC 1951) #ifndef CRYPTOPP_ZDEFLATE_H #define CRYPTOPP_ZDEFLATE_H @@ -12,14 +12,14 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class LowFirstBitWriter -//! \brief Encoding table writer -//! \since Crypto++ 1.0 +/// \class LowFirstBitWriter +/// \brief Encoding table writer +/// \since Crypto++ 1.0 class LowFirstBitWriter : public Filter { public: - //! \brief Construct a LowFirstBitWriter - //! \param attachment an attached transformation + /// \brief Construct a LowFirstBitWriter + /// \param attachment an attached transformation LowFirstBitWriter(BufferedTransformation *attachment); void PutBits(unsigned long value, unsigned int length); @@ -37,26 +37,26 @@ protected: FixedSizeSecBlock m_outputBuffer; }; -//! \class HuffmanEncoder -//! \brief Huffman Encoder -//! \since Crypto++ 1.0 +/// \class HuffmanEncoder +/// \brief Huffman Encoder +/// \since Crypto++ 1.0 class HuffmanEncoder { public: typedef unsigned int code_t; typedef unsigned int value_t; - //! \brief Construct a HuffmanEncoder + /// \brief Construct a HuffmanEncoder HuffmanEncoder() {} - //! \brief Construct a HuffmanEncoder - //! \param codeBits a table of code bits - //! \param nCodes the number of codes in the table + /// \brief Construct a HuffmanEncoder + /// \param codeBits a table of code bits + /// \param nCodes the number of codes in the table HuffmanEncoder(const unsigned int *codeBits, unsigned int nCodes); - //! \brief Initialize or reinitialize this object - //! \param codeBits a table of code bits - //! \param nCodes the number of codes in the table + /// \brief Initialize or reinitialize this object + /// \param codeBits a table of code bits + /// \param nCodes the number of codes in the table void Initialize(const unsigned int *codeBits, unsigned int nCodes); static void GenerateCodeLengths(unsigned int *codeBits, unsigned int maxCodeBits, const unsigned int *codeCounts, size_t nCodes); @@ -72,56 +72,56 @@ public: SecBlock m_valueToCode; }; -//! \class Deflator -//! \brief DEFLATE compressor (RFC 1951) -//! \since Crypto++ 1.0 +/// \class Deflator +/// \brief DEFLATE compressor (RFC 1951) +/// \since Crypto++ 1.0 class Deflator : public LowFirstBitWriter { public: - //! \brief Deflate level as enumerated values. + /// \brief Deflate level as enumerated values. enum { - //! \brief Minimum deflation level, fastest speed (0) + /// \brief Minimum deflation level, fastest speed (0) MIN_DEFLATE_LEVEL = 0, - //! \brief Default deflation level, compromise between speed (6) + /// \brief Default deflation level, compromise between speed (6) DEFAULT_DEFLATE_LEVEL = 6, - //! \brief Minimum deflation level, slowest speed (9) + /// \brief Minimum deflation level, slowest speed (9) MAX_DEFLATE_LEVEL = 9}; - //! \brief Windows size as enumerated values. + /// \brief Windows size as enumerated values. enum { - //! \brief Minimum window size, smallest table (9) + /// \brief Minimum window size, smallest table (9) MIN_LOG2_WINDOW_SIZE = 9, - //! \brief Default window size (15) + /// \brief Default window size (15) DEFAULT_LOG2_WINDOW_SIZE = 15, - //! \brief Maximum window size, largest table (15) + /// \brief Maximum window size, largest table (15) MAX_LOG2_WINDOW_SIZE = 15}; - //! \brief Construct a Deflator compressor - //! \param attachment an attached transformation - //! \param deflateLevel the deflate level - //! \param log2WindowSize the window size - //! \param detectUncompressible flag to detect if data is compressible - //! \details detectUncompressible makes it faster to process uncompressible files, but - //! if a file has both compressible and uncompressible parts, it may fail to compress - //! some of the compressible parts. + /// \brief Construct a Deflator compressor + /// \param attachment an attached transformation + /// \param deflateLevel the deflate level + /// \param log2WindowSize the window size + /// \param detectUncompressible flag to detect if data is compressible + /// \details detectUncompressible makes it faster to process uncompressible files, but + /// if a file has both compressible and uncompressible parts, it may fail to compress + /// some of the compressible parts. Deflator(BufferedTransformation *attachment=NULLPTR, int deflateLevel=DEFAULT_DEFLATE_LEVEL, int log2WindowSize=DEFAULT_LOG2_WINDOW_SIZE, bool detectUncompressible=true); - //! \brief Construct a Deflator compressor - //! \param parameters a set of NameValuePairs to initialize this object - //! \param attachment an attached transformation - //! \details Possible parameter names: Log2WindowSize, DeflateLevel, DetectUncompressible + /// \brief Construct a Deflator compressor + /// \param parameters a set of NameValuePairs to initialize this object + /// \param attachment an attached transformation + /// \details Possible parameter names: Log2WindowSize, DeflateLevel, DetectUncompressible Deflator(const NameValuePairs ¶meters, BufferedTransformation *attachment=NULLPTR); - //! \brief Sets the deflation level - //! \param deflateLevel the level of deflation - //! \details SetDeflateLevel can be used to set the deflate level in the middle of compression + /// \brief Sets the deflation level + /// \param deflateLevel the level of deflation + /// \details SetDeflateLevel can be used to set the deflate level in the middle of compression void SetDeflateLevel(int deflateLevel); - //! \brief Retrieves the deflation level - //! \returns the level of deflation + /// \brief Retrieves the deflation level + /// \returns the level of deflation int GetDeflateLevel() const {return m_deflateLevel;} - //! \brief Retrieves the window size - //! \returns the windows size + /// \brief Retrieves the window size + /// \returns the windows size int GetLog2WindowSize() const {return m_log2WindowSize;} void IsolatedInitialize(const NameValuePairs ¶meters); diff --git a/zinflate.h b/zinflate.h index 0767d4f9..035b095e 100644 --- a/zinflate.h +++ b/zinflate.h @@ -8,8 +8,8 @@ NAMESPACE_BEGIN(CryptoPP) -//! \class LowFirstBitReader -//! \since Crypto++ 1.0 +/// \class LowFirstBitReader +/// \since Crypto++ 1.0 class LowFirstBitReader { public: @@ -30,9 +30,9 @@ private: struct CodeLessThan; -//! \class HuffmanDecoder -//! \brief Huffman Decoder -//! \since Crypto++ 1.0 +/// \class HuffmanDecoder +/// \brief Huffman Decoder +/// \since Crypto++ 1.0 class HuffmanDecoder { public: @@ -86,9 +86,9 @@ private: mutable std::vector > m_cache; }; -//! \class Inflator -//! \brief DEFLATE decompressor (RFC 1951) -//! \since Crypto++ 1.0 +/// \class Inflator +/// \brief DEFLATE decompressor (RFC 1951) +/// \since Crypto++ 1.0 class Inflator : public AutoSignaling { public: @@ -98,17 +98,17 @@ public: Err(ErrorType e, const std::string &s) : Exception(e, s) {} }; - //! \brief Exception thrown when a truncated stream is encountered + /// \brief Exception thrown when a truncated stream is encountered class UnexpectedEndErr : public Err {public: UnexpectedEndErr() : Err(INVALID_DATA_FORMAT, "Inflator: unexpected end of compressed block") {}}; - //! \brief Exception thrown when a bad block is encountered + /// \brief Exception thrown when a bad block is encountered class BadBlockErr : public Err {public: BadBlockErr() : Err(INVALID_DATA_FORMAT, "Inflator: error in compressed block") {}}; - //! \brief Exception thrown when an invalid distance is encountered + /// \brief Exception thrown when an invalid distance is encountered class BadDistanceErr : public Err {public: BadDistanceErr() : Err(INVALID_DATA_FORMAT, "Inflator: error in bit distance") {}}; - //! \brief RFC 1951 Decompressor - //! \param attachment the filter's attached transformation - //! \param repeat decompress multiple compressed streams in series - //! \param autoSignalPropagation 0 to turn off MessageEnd signal + /// \brief RFC 1951 Decompressor + /// \param attachment the filter's attached transformation + /// \param repeat decompress multiple compressed streams in series + /// \param autoSignalPropagation 0 to turn off MessageEnd signal Inflator(BufferedTransformation *attachment = NULLPTR, bool repeat = false, int autoSignalPropagation = -1); void IsolatedInitialize(const NameValuePairs ¶meters); diff --git a/zlib.h b/zlib.h index b8e87f99..ef10856f 100644 --- a/zlib.h +++ b/zlib.h @@ -37,10 +37,10 @@ public: class UnsupportedAlgorithm : public Err {public: UnsupportedAlgorithm() : Err(INVALID_DATA_FORMAT, "ZlibDecompressor: unsupported algorithm") {}}; class UnsupportedPresetDictionary : public Err {public: UnsupportedPresetDictionary() : Err(INVALID_DATA_FORMAT, "ZlibDecompressor: unsupported preset dictionary") {}}; - //! \brief Construct a ZlibDecompressor - //! \param attachment a \ BufferedTransformation to attach to this object - //! \param repeat decompress multiple compressed streams in series - //! \param autoSignalPropagation 0 to turn off MessageEnd signal + /// \brief Construct a ZlibDecompressor + /// \param attachment a \ BufferedTransformation to attach to this object + /// \param repeat decompress multiple compressed streams in series + /// \param autoSignalPropagation 0 to turn off MessageEnd signal ZlibDecompressor(BufferedTransformation *attachment = NULLPTR, bool repeat = false, int autoSignalPropagation = -1); unsigned int GetLog2WindowSize() const {return m_log2WindowSize;}