diff --git a/cryptlib.h b/cryptlib.h index 7dfa1ca4..c57f32f5 100644 --- a/cryptlib.h +++ b/cryptlib.h @@ -99,6 +99,7 @@ class RandomNumberGenerator; class BufferedTransformation; //! \brief Specifies a direction for a cipher to operate +//! \sa BlockTransformation::IsForwardTransformation(), BlockTransformation::IsPermutation(), BlockTransformation::GetCipherDirection() enum CipherDir { //! \brief the cipher is performing encryption ENCRYPTION, @@ -117,6 +118,8 @@ struct EnumToType }; //! \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 LITTLE_ENDIAN_ORDER = 0, @@ -242,11 +245,11 @@ struct CRYPTOPP_DLL DecodingResult //! \brief Compare two DecodingResult //! \param rhs the other DecodingResult - //! \returns true if both isValidCoding and messageLength are equal, false otherwise + //! \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 - //! \returns true if either isValidCoding or messageLength is \a not equal, false otherwise + //! \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);} @@ -291,11 +294,11 @@ public: , m_stored(stored), m_retrieving(retrieving) {} //! \brief Provides the stored type - //! \returns the C++ mangled name of the type + //! \return the C++ mangled name of the type const std::type_info & GetStoredTypeInfo() const {return m_stored;} //! \brief Provides the retrieveing type - //! \returns the C++ mangled name of the type + //! \return the C++ mangled name of the type const std::type_info & GetRetrievingTypeInfo() const {return m_retrieving;} private: @@ -325,7 +328,7 @@ public: //! \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 + //! \return true if the value was retrieved, false otherwise //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), //! GetRequiredParameter() and GetRequiredIntParameter() template @@ -338,7 +341,7 @@ public: //! \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 - //! \returns the object or value + //! \return the object or value //! \sa GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), //! GetRequiredParameter() and GetRequiredIntParameter() template @@ -352,7 +355,7 @@ public: } //! \brief Get a list of value names that can be retrieved - //! \returns a list of names available to retrieve + //! \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;} @@ -360,7 +363,7 @@ public: //! \brief Get a named value with type int //! \param name the name of the value to retrieve //! \param value the value retrieved upon success - //! \returns true if an int value was retrieved, false otherwise + //! \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(), @@ -371,7 +374,7 @@ public: //! \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 - //! \returns the value retrieved on success or the default value + //! \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 @@ -425,7 +428,7 @@ public: //! \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 + //! \return true if the value was retrieved, false otherwise //! \details GetVoidValue() retrives 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. @@ -470,7 +473,7 @@ public: virtual ~Clonable() {} //! \brief Copies this object - //! \returns a copy of this object + //! \return a copy of this object //! \throws NotImplemented //! \note this is \a not implemented by most classes //! \sa NotCopyable @@ -493,7 +496,7 @@ public: Algorithm(bool checkSelfTestStatus = true); //! \brief Provides the name of this algorithm - //! \returns the standard algorithm name + //! \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. @@ -522,12 +525,12 @@ public: //! \brief //! \param n the desired keylength - //! \returns the smallest valid key length in bytes that is greater than or equal to min(n, GetMaxKeyLength()) + //! \return the smallest valid key length in bytes that is greater than or equal to min(n, GetMaxKeyLength()) virtual size_t GetValidKeyLength(size_t n) const =0; //! \brief Returns whether keylength is a valid key length //! \param keylength the requested keylength - //! \returns true if keylength is valid, false otherwise + //! \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);} @@ -588,21 +591,21 @@ public: }; //! \brief Minimal requirement for secure IVs - //! \returns the secure IV requirement of the algorithm + //! \return the secure IV requirement of the algorithm virtual IV_Requirement IVRequirement() const =0; //! \brief Determines if the object can be resynchronized - //! \returns true if the object can be resynchronized (i.e. supports initialization vectors), false otherwise + //! \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 - //! \returns true if the object can use random IVs (in addition to ones returned by GetNextIV), false otherwise + //! \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 - //! \returns true if the object can use random but possibly predictable IVs (in addition to ones returned by + //! \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;} @@ -612,23 +615,23 @@ public: bool CanUseStructuredIVs() const {return IVRequirement() <= UNIQUE_IV;} //! \brief Returns length of the IV accepted by this object - //! \returns the size of an IV, in bytes + //! \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 - //! \returns default length of IVs accepted by this object, in bytes + //! \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 - //! \returns minimal length of IVs accepted by this object, in bytes + //! \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 - //! \returns maximal length of IVs accepted by this object, in bytes + //! \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();} @@ -655,7 +658,7 @@ public: protected: //! \brief Returns the base class Algorithm - //! \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 @@ -694,7 +697,7 @@ protected: //! \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 - //! \returns a pointer to the first byte of the IV + //! \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); @@ -744,18 +747,18 @@ public: {ProcessAndXorBlock(inoutBlock, NULL, inoutBlock);} //! Provides the block size of the cipher - //! \returns the block size of the cipher, in bytes + //! \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. - //! \returns the input data alignment that provides 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) 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 + //! \return true if DIR is ENCRYPTION, false otherwise //! \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection() virtual bool IsForwardTransformation() const =0; @@ -787,7 +790,9 @@ public: //! \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; - //! \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection() + //! \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;} #ifndef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562 @@ -802,27 +807,27 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE StreamTransformation : public Algorithm { public: //! \brief Provides a reference to this object - //! \returns 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 - //! \returns The block size of the cipher if input must be processed in blocks, 1 otherwise + //! \return The block size of the cipher if input must be processed in blocks, 1 otherwise virtual unsigned int MandatoryBlockSize() const {return 1;} //! \brief Provides the input block size most efficient for this cipher. - //! \returns The input block size that is most efficient for the 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. - //! \returns the number of bytes used in the current block when processing at the 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. - //! \returns the input data alignment that provides optimal performance + //! \return the input data alignment that provides optimal performance virtual unsigned int OptimalDataAlignment() const; //! \brief Encrypt or decrypt an array of bytes @@ -865,7 +870,7 @@ public: {ProcessData(&input, &input, 1); return input;} //! \brief Determines whether the cipher supports random access - //! \returns true if the cipher supports random access, false otherwise + //! \return true if the cipher supports random access, false otherwise virtual bool IsRandomAccess() const =0; //! \brief Seek to an absolute position @@ -881,13 +886,13 @@ public: } //! \brief Determines whether the cipher is self-inverting - //! \returns true if the cipher is self-inverting, false otherwise + //! \return 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 + //! \return true if DIR is ENCRYPTION, false otherwise //! \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection() virtual bool IsForwardTransformation() const =0; @@ -908,7 +913,7 @@ class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE HashTransformation : public Algorithm { public: //! \brief Provides a reference to this object - //! \returns 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;} @@ -940,30 +945,30 @@ public: {TruncatedFinal(NULL, 0);} //! Provides the digest size of the hash - //! \returns the digest size of the hash. + //! \return the digest size of the hash. //! \details Calls to Final() require a buffer that is equal to (or greater than) DigestSize(). virtual unsigned int DigestSize() const =0; //! Provides the tag size of the hash - //! \returns 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 - //! \returns the block size of the compression function, in bytes + //! \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. - //! \returns The input block size that is most efficient for the 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 1;} //! \brief Provides input and output data alignment for optimal performance - //! \returns the input data alignment that provides 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 @@ -978,7 +983,7 @@ public: //! \brief Verifies the hash of the current message //! \param digest a pointer to the buffer of an \a existing hash - //! \returns \p true if the existing hash matches the computed hash, \p false otherwise + //! \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 Calls to Verify() require a buffer that is equal to (or greater than) DigestSize(). //! \details Verify() performs a bitwise compare on the buffers using VerifyBufsEqual(), which is @@ -991,7 +996,7 @@ public: //! \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 - //! \returns \p true if the existing hash matches the computed hash, \p false otherwise + //! \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 @@ -1022,7 +1027,7 @@ public: //! \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 - //! \returns \p true if the existing hash matches the computed hash, \p false otherwise + //! \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(). @@ -1036,7 +1041,7 @@ public: //! \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 - //! \returns \p true if the existing hash matches the computed hash, \p false otherwise + //! \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. @@ -1061,7 +1066,7 @@ protected: typedef HashTransformation HashFunction; //! \brief Interface for one direction (encryption or decryption) of a block cipher -/*! \note These objects usually should not be used directly. See BlockTransformation for more details. */ +//! \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: @@ -1069,6 +1074,7 @@ protected: }; //! \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: @@ -1076,6 +1082,7 @@ protected: }; //! \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: @@ -1083,12 +1090,15 @@ protected: }; //! \brief 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/decrypt the data, and the MessageAuthenticationCode part of this - interface is used to input additional authenticated data (AAD, which is MAC'ed but not encrypted), and to generate/verify the MAC. */ +//! \details The StreamTransformation part of this interface is used to encrypt/decrypt the data, and the +//! MessageAuthenticationCode part of this interface is used to input additional authenticated data (AAD, +//! which is MAC'ed but not encrypted), and to generate/verify the MAC. class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AuthenticatedSymmetricCipher : public MessageAuthenticationCode, public StreamTransformation { public: - //! 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: @@ -1096,23 +1106,41 @@ public: explicit BadState(const std::string &name, const char *function, const char *state) : Exception(OTHER_ERROR, name + ": " + function + " was called before " + state) {} }; - //! 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; - //! 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; - //! 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;} - //! if this function returns true, SpecifyDataLengths() must be called before attempting to input data - /*! This is the case for some schemes, such as CCM. */ + //! \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;} - //! this function only needs to be called if NeedsPrespecifiedDataLengths() returns true + //! \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); - //! encrypt and generate MAC in one call. will truncate MAC if macSize < TagSize() + //! \brief Encrypts and calculates a MAC in one call + //! \return true if the authenticated encryption succeeded, false otherwise + //! \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); - //! decrypt and verify MAC in one call, returning true iff MAC is valid. 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); - // redeclare this to avoid compiler ambiguity errors + //! \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; #ifndef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562 @@ -1141,7 +1169,7 @@ public: //! \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 + //! \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. @@ -1152,18 +1180,18 @@ public: } //! \brief Determines if a generator can accept additional entropy - //! \returns true if IncorporateEntropy() is implemented + //! \return true if IncorporateEntropy() is implemented virtual bool CanIncorporateEntropy() const {return false;} //! \brief Generate new random byte and return it - //! \returns a random 8-bit byte + //! \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 contraints of a particular generator. virtual byte GenerateByte(); //! \brief Generate new random bit and return it - //! \returns a random bit + //! \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 contraints of a particular generator. @@ -1172,7 +1200,7 @@ public: //! \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 - //! \returns a random 32-bit word + //! \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 @@ -1230,11 +1258,11 @@ public: }; //! \brief Random Number Generator that does not produce random numbers -//! \returns reference that can be passed to functions that require a RandomNumberGenerator +//! \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, IsProbabilistic() +//! \sa ClassNullRNG, PK_SignatureScheme::IsProbabilistic() CRYPTOPP_DLL RandomNumberGenerator & CRYPTOPP_API NullRNG(); //! \class WaitObjectContainer @@ -1249,6 +1277,7 @@ public: virtual ~Waitable() {} //! \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 @@ -1261,8 +1290,10 @@ public: //! innerThing.GetWaitObjects(c, CallStack("MyClass::GetWaitObjects at X", &callStack));. virtual void GetWaitObjects(WaitObjectContainer &container, CallStack const& callStack) =0; - //! wait on this object - /*! same as creating an empty container, calling GetWaitObjects(), and 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); }; @@ -1306,7 +1337,7 @@ public: BufferedTransformation() : Algorithm(false) {} //! \brief Provides a reference to this object - //! \returns 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;} @@ -1316,7 +1347,7 @@ public: //! \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. - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + //! \return the number of bytes that remain in the block (i.e., bytes not processed) //! \details Put(byte) calls Put(byte*, size_t). size_t Put(byte inByte, bool blocking=true) {return Put(&inByte, 1, blocking);} @@ -1325,7 +1356,7 @@ public: //! \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 - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + //! \return the number of bytes that remain in the block (i.e., bytes not processed) //! \details Internally, Put() calls Put2(). size_t Put(const byte *inString, size_t length, bool blocking=true) {return Put2(inString, length, 0, blocking);} @@ -1334,14 +1365,14 @@ public: //! \param value the 16-bit value to be processed //! \param order the ByteOrder in which the word should be processed //! \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) + //! \return the number of bytes that remain in the block (i.e., bytes not 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 in which the word should be processed. //! \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) + //! \return the number of bytes that remain in the block (i.e., bytes not 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 @@ -1357,7 +1388,7 @@ public: {size=0; return NULL;} //! \brief Determines whether input can be modifed by the callee - //! \returns true if input can be modified, false otherwise + //! \return true if input can be modified, false otherwise //! \details The base class implementation returns false. virtual bool CanModifyInput() const {return false;} @@ -1366,7 +1397,7 @@ public: //! \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 - //! \returns 0 indicates all bytes were processed during the call. Non-0 indicates the + //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the //! number of bytes that were \a not processed size_t PutModifiable(byte *inString, size_t length, bool blocking=true) {return PutModifiable2(inString, length, 0, blocking);} @@ -1384,7 +1415,7 @@ public: //! \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 - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + //! \return the number of bytes that remain in the block (i.e., bytes not 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 @@ -1506,6 +1537,8 @@ public: {CRYPTOPP_UNUSED(propagation);} //! \brief Retrieve automatic signal propagation value + //! \return the number of attached transformations the signal is propogated to. 0 indicates + //! the signal is only witnessed by this object virtual int GetAutoSignalPropagation() const {return 0;} public: @@ -1518,31 +1551,31 @@ public: //@{ //! \brief Provides the number of bytes ready for retrieval - //! \returns 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 + //! \return 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 - //! \returns the number of bytes consumed during the call. + //! \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 - //! \returns the number of bytes consumed during the call. + //! \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 - //! \returns the number of bytes read during the call. + //! \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; @@ -1550,7 +1583,7 @@ public: //! \brief Peek a block of bytes //! \param outString a block of bytes //! \param peekMax the number of bytes to Peek - //! \returns the number of bytes read during the call. + //! \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; @@ -1558,21 +1591,21 @@ public: //! \brief Retrieve a 16-bit word //! \param value the 16-bit value to be retrieved //! \param order the ByteOrder in which the word should be retrieved - //! \returns the number of bytes consumed during the call. + //! \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 in which the word should be retrieved - //! \returns the number of bytes consumed during the call. + //! \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 in which the word should be retrieved - //! \returns the number of bytes consumed during the call. + //! \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; @@ -1580,7 +1613,7 @@ public: //! \brief Peek a 32-bit word //! \param value the 32-bit value to be retrieved //! \param order the ByteOrder in which the word should be retrieved - //! \returns the number of bytes consumed during the call. + //! \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; @@ -1591,7 +1624,7 @@ public: //! \param target the destination BufferedTransformation //! \param transferMax the number of bytes to transfer //! \param channel the channel on which the transfer should occur - //! \returns the number of bytes transferred during the call. + //! \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) @@ -1608,7 +1641,7 @@ public: //! \param target the destination BufferedTransformation //! \param copyMax the number of bytes to copy //! \param channel the channel on which the transfer should occur - //! \returns the number of bytes copied during the call. + //! \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 @@ -1619,7 +1652,7 @@ public: //! \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 - //! \returns the number of bytes copied during the call. + //! \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. @@ -1636,28 +1669,28 @@ public: //@{ //! \brief Provides the number of bytes ready for retrieval - //! \returns 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 - //! \returns 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 + //! \return true if NumberOfMessages() > 0, false otherwise //! \details AnyMessages returns true if NumberOfMessages() > 0 virtual bool AnyMessages() const; //! \brief Start retrieving the next message - //! \returns true if a message is ready for retrieval + //! \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 - //! \returns 0 if the requested number of messages was skipped, non-0 otherwise + //! \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(). @@ -1667,35 +1700,52 @@ public: //! \param target the destination BufferedTransformation //! \param count the number of messages to transfer //! \param channel the channel on which the transfer should occur - //! \returns 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. + //! \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 Copies messages from this object to another BufferedTransformation + //! \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 - //! \returns the number of bytes that remain in the current transfer block (i.e., bytes not transferred) + //! \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 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 + //! \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. + //! 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. 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. virtual bool GetNextMessageSeries() {return false;} + //! \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 virtual unsigned int NumberOfMessageSeries() const {return 0;} //@} @@ -1710,12 +1760,12 @@ public: //! \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 - //! \returns 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. + //! \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 + //! 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; @@ -1728,12 +1778,12 @@ public: //! \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 - //! \returns the number of bytes that remain in the copy block (i.e., bytes not copied) + //! \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 + //! \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 tahn 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; @@ -1746,8 +1796,11 @@ public: //! \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 - //! \returns 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. + //! \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 @@ -1756,8 +1809,8 @@ public: //! \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 - //! \returns 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. + //! \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); //@} @@ -1774,7 +1827,7 @@ public: //! \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. - //! \returns 0 indicates all bytes were processed during the call. Non-0 indicates the + //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the //! number of bytes that were \a not processed. size_t ChannelPut(const std::string &channel, byte inByte, bool blocking=true) {return ChannelPut(channel, &inByte, 1, blocking);} @@ -1784,7 +1837,7 @@ public: //! \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 - //! \returns 0 indicates all bytes were processed during the call. Non-0 indicates the + //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the //! number of bytes that were \a 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);} @@ -1794,7 +1847,7 @@ public: //! \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 - //! \returns 0 indicates all bytes were processed during the call. Non-0 indicates the + //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the //! number of bytes that were \a not processed. size_t ChannelPutModifiable(const std::string &channel, byte *inString, size_t length, bool blocking=true) {return ChannelPutModifiable2(channel, inString, length, 0, blocking);} @@ -1804,7 +1857,7 @@ public: //! \param value the 16-bit value to be processed. //! \param order the ByteOrder in which the word should be processed. //! \param blocking specifies whether the object should block when processing input. - //! \returns 0 indicates all bytes were processed during the call. Non-0 indicates the + //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the //! number of bytes that were \a not processed. size_t ChannelPutWord16(const std::string &channel, word16 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true); @@ -1813,7 +1866,7 @@ public: //! \param value the 32-bit value to be processed. //! \param order the ByteOrder in which the word should be processed. //! \param blocking specifies whether the object should block when processing input. - //! \returns 0 indicates all bytes were processed during the call. Non-0 indicates the + //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the //! number of bytes that were \a not processed. size_t ChannelPutWord32(const std::string &channel, word32 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true); @@ -1821,7 +1874,7 @@ public: //! \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 - //! \returns 0 indicates all bytes were processed during the call. Non-0 indicates the + //! \return 0 indicates all bytes were processed during the call. Non-0 indicates the //! number of bytes that were \a not processed. //! \details propagation count includes this object. Setting propagation to 1 means this //! object only. Setting propagation to -1 means unlimited propagation. @@ -1834,7 +1887,7 @@ public: //! \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 - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + //! \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) @@ -1843,7 +1896,7 @@ public: //! \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 - //! \returns a pointer to a memroy block with length size + //! \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 @@ -1859,7 +1912,7 @@ public: //! \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. - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + //! \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 @@ -1868,7 +1921,7 @@ public: //! \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 - //! \returns the number of bytes that remain in the block (i.e., bytes not processed) + //! \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 @@ -1876,7 +1929,7 @@ public: //! \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 - //! \returns true of the Flush was successful + //! \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); @@ -1899,26 +1952,24 @@ public: //@} //! \name ATTACHMENT - /*! 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. - */ + //! \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 - //! \returns true if the object allows an attachment, false otherwise + //! \return true if the object allows an attachment, false otherwise //! \details Sources and Filters will return true, while Sinks and other objects will return false. virtual bool Attachable() {return false;} //! \brief Returns the object immediately attached to this object - //! \returns the attached transformation + //! \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() {assert(!Attachable()); return 0;} //! \brief Returns the object immediately attached to this object - //! \returns the attached transformation + //! \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 @@ -1946,7 +1997,7 @@ public: protected: //! \brief Decrements the propagation count while clamping at 0 - //! \returns the decremented propagation or 0 + //! \return the decremented propagation or 0 static int DecrementPropagation(int propagation) {return propagation != 0 ? propagation - 1 : 0;} @@ -1955,7 +2006,7 @@ private: }; //! \brief An input discarding BufferedTransformation -//! \returns a reference to a BufferedTransformation object that discards all input +//! \return a reference to a BufferedTransformation object that discards all input CRYPTOPP_DLL BufferedTransformation & TheBitBucket(); //! \class CryptoMaterial @@ -1963,7 +2014,7 @@ CRYPTOPP_DLL BufferedTransformation & TheBitBucket(); 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: @@ -1971,13 +2022,13 @@ public: }; //! \brief Assign values to this object - /*! \details This function can be used to create a public key from a private key. */ + //! \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 + //! \return true if the tests succeed, false otherwise //! \details There are four levels of thoroughness: //!