- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

# cryptlib.h

Go to the documentation of this file.

    00001 // cryptlib.h - written and placed in the public domain by Wei Dai
    00002 /*! \file
    00003         This file contains the declarations for the abstract base
    00004         classes that provide a uniform interface to this library.
    00005 */
    00006
    00007 /*!     \mainpage <a href="http://www.cryptopp.com">Crypto++</a><sup><small>&reg;</small></sup> Library 5.4 Reference Manual
    00008 <dl>
    00009 <dt>Abstract Base Classes<dd>
    00010         cryptlib.h
    00011 <dt>Symmetric Ciphers<dd>
    00012         SymmetricCipherDocumentation
    00013 <dt>Hash Functions<dd>
    00014         HAVAL, MD2, MD4, MD5, PanamaHash, RIPEMD160, RIPEMD320, RIPEMD128, RIPEMD256, SHA1, SHA224, SHA256, SHA384, SHA512, Tiger, Whirlpool
    00015 <dt>Non-Cryptographic Checksums<dd>
    00016         CRC32, Adler32
    00017 <dt>Message Authentication Codes<dd>
    00018         #MD5MAC, XMACC, HMAC, CBC_MAC, DMAC, PanamaMAC, TTMAC
    00019 <dt>Random Number Generators<dd>
    00020         NullRNG(), LC_RNG, RandomPool, BlockingRng, NonblockingRng, AutoSeededRandomPool, AutoSeededX917RNG
    00021 <dt>Password-based Cryptography<dd>
    00022         PasswordBasedKeyDerivationFunction
    00023 <dt>Public Key Cryptosystems<dd>
    00024         DLIES, ECIES, LUCES, RSAES, RabinES, LUC_IES
    00025 <dt>Public Key Signature Schemes<dd>
    00026         DSA, GDSA, ECDSA, NR, ECNR, LUCSS, RSASS, RSASS_ISO, RabinSS, RWSS, ESIGN
    00027 <dt>Key Agreement<dd>
    00028         #DH, DH2, #MQV, ECDH, ECMQV, XTR_DH
    00029 <dt>Algebraic Structures<dd>
    00030         Integer, PolynomialMod2, PolynomialOver, RingOfPolynomialsOver,
    00031         ModularArithmetic, MontgomeryRepresentation, GFP2_ONB,
    00032         GF2NP, GF256, GF2_32, EC2N, ECP
    00033 <dt>Secret Sharing and Information Dispersal<dd>
    00034         SecretSharing, SecretRecovery, InformationDispersal, InformationRecovery
    00035 <dt>Compression<dd>
    00036         Deflator, Inflator, Gzip, Gunzip, ZlibCompressor, ZlibDecompressor
    00037 <dt>Input Source Classes<dd>
    00038         StringSource, FileSource, SocketSource, WindowsPipeSource, RandomNumberSource
    00039 <dt>Output Sink Classes<dd>
    00040         StringSinkTemplate, ArraySink, FileSink, SocketSink, WindowsPipeSink
    00041 <dt>Filter Wrappers<dd>
    00042         StreamTransformationFilter, HashFilter, HashVerificationFilter, SignerFilter, SignatureVerificationFilter
    00043 <dt>Binary to Text Encoders and Decoders<dd>
    00044         HexEncoder, HexDecoder, Base64Encoder, Base64Decoder, Base32Encoder, Base32Decoder
    00045 <dt>Wrappers for OS features<dd>
    00046         Timer, Socket, WindowsHandle, ThreadLocalStorage, ThreadUserTimer
    00047 <dt>FIPS 140 related<dd>
    00048         fips140.h
    00049 </dl>
    00050
    00051 In the FIPS 140-2 validated DLL version of Crypto++, only the following implementation class are available.
    00052 <dl>
    00053 <dt>Block Ciphers<dd>
    00054         AES, DES_EDE2, DES_EDE3, SKIPJACK
    00055 <dt>Cipher Modes (replace template parameter BC with one of the block ciphers above)<dd>
    00056         ECB_Mode<BC>, CTR_Mode<BC>, CBC_Mode<BC>, CFB_FIPS_Mode<BC>, OFB_Mode<BC>
    00057 <dt>Hash Functions<dd>
    00058         SHA1, SHA224, SHA256, SHA384, SHA512
    00059 <dt>Public Key Signature Schemes (replace template parameter H with one of the hash functions above)<dd>
    00060         RSASS<PKCS1v15, H>, RSASS<PSS, H>, RSASS_ISO<H>, RWSS<P1363_EMSA2, H>, DSA, ECDSA<ECP, H>, ECDSA<EC2N, H>
    00061 <dt>Message Authentication Codes (replace template parameter H with one of the hash functions above)<dd>
    00062         HMAC<H>, CBC_MAC<DES_EDE2>, CBC_MAC<DES_EDE3>
    00063 <dt>Random Number Generators<dd>
    00064         AutoSeededX917RNG<DES_EDE3>
    00065 <dt>Key Agreement<dd>
    00066         #DH
    00067 <dt>Public Key Cryptosystems<dd>
    00068         RSAES<OAEP<SHA1> >
    00069 </dl>
    00070
    00071 <p>This reference manual is a work in progress. Some classes are still lacking detailed descriptions.
    00072 <p>Click <a href="CryptoPPRef.zip">here</a> to download a zip archive containing this manual.
    00073 <p>Thanks to Ryan Phillips for providing the Doxygen configuration file
    00074 and getting me started with this manual.
    00075 */
    00076
    00077 #ifndef CRYPTOPP_CRYPTLIB_H
    00078 #define CRYPTOPP_CRYPTLIB_H
    00079
    00080 #include "config.h"
    00081 #include "stdcpp.h"
    00082
    00083 NAMESPACE_BEGIN(CryptoPP)
    00084
    00085 // forward declarations
    00086 class Integer;
    00087
    00088 //! used to specify a direction for a cipher to operate in (encrypt or decrypt)
    00089 enum CipherDir {ENCRYPTION,     DECRYPTION};
    00090
    00091 //! used to represent infinite time
    00092 const unsigned long INFINITE_TIME = ULONG_MAX;
    00093
    00094 // VC60 workaround: using enums as template parameters causes problems
    00095 template <typename ENUM_TYPE, int VALUE>
    00096 struct EnumToType
    00097 {
    00098         static ENUM_TYPE ToEnum() {return (ENUM_TYPE)VALUE;}
    00099 };
    00100
    00101 enum ByteOrder {LITTLE_ENDIAN_ORDER = 0, BIG_ENDIAN_ORDER = 1};
    00102 typedef EnumToType<ByteOrder, LITTLE_ENDIAN_ORDER> LittleEndian;
    00103 typedef EnumToType<ByteOrder, BIG_ENDIAN_ORDER> BigEndian;
    00104
    00105 //! base class for all exceptions thrown by Crypto++
    00106 class CRYPTOPP_DLL Exception : public std::exception
    00107 {
    00108 public:
    00109         //! error types
    00110         enum ErrorType {
    00111                 //! a method is not implemented
    00112                 NOT_IMPLEMENTED,
    00113                 //! invalid function argument
    00114                 INVALID_ARGUMENT,
    00115                 //! BufferedTransformation received a Flush(true) signal but can't flush buffers
    00116                 CANNOT_FLUSH,
    00117                 //! data integerity check (such as CRC or MAC) failed
    00118                 DATA_INTEGRITY_CHECK_FAILED,
    00119                 //! received input data that doesn't conform to expected format
    00120                 INVALID_DATA_FORMAT,
    00121                 //! error reading from input device or writing to output device
    00122                 IO_ERROR,
    00123                 //! some error not belong to any of the above categories
    00124                 OTHER_ERROR
    00125         };
    00126
    00127         explicit Exception(ErrorType errorType, const std::string &s) : m_errorType(errorType), m_what(s) {}
    00128         virtual ~Exception() throw() {}
    00129         const char *what() const throw() {return (m_what.c_str());}
    00130         const std::string &GetWhat() const {return m_what;}
    00131         void SetWhat(const std::string &s) {m_what = s;}
    00132         ErrorType GetErrorType() const {return m_errorType;}
    00133         void SetErrorType(ErrorType errorType) {m_errorType = errorType;}
    00134
    00135 private:
    00136         ErrorType m_errorType;
    00137         std::string m_what;
    00138 };
    00139
    00140 //! exception thrown when an invalid argument is detected
    00141 class CRYPTOPP_DLL InvalidArgument : public Exception
    00142 {
    00143 public:
    00144         explicit InvalidArgument(const std::string &s) : Exception(INVALID_ARGUMENT, s) {}
    00145 };
    00146
    00147 //! exception thrown when input data is received that doesn't conform to expected format
    00148 class CRYPTOPP_DLL InvalidDataFormat : public Exception
    00149 {
    00150 public:
    00151         explicit InvalidDataFormat(const std::string &s) : Exception(INVALID_DATA_FORMAT, s) {}
    00152 };
    00153
    00154 //! exception thrown by decryption filters when trying to decrypt an invalid ciphertext
    00155 class CRYPTOPP_DLL InvalidCiphertext : public InvalidDataFormat
    00156 {
    00157 public:
    00158         explicit InvalidCiphertext(const std::string &s) : InvalidDataFormat(s) {}
    00159 };
    00160
    00161 //! exception thrown by a class if a non-implemented method is called
    00162 class CRYPTOPP_DLL NotImplemented : public Exception
    00163 {
    00164 public:
    00165         explicit NotImplemented(const std::string &s) : Exception(NOT_IMPLEMENTED, s) {}
    00166 };
    00167
    00168 //! exception thrown by a class when Flush(true) is called but it can't completely flush its buffers
    00169 class CRYPTOPP_DLL CannotFlush : public Exception
    00170 {
    00171 public:
    00172         explicit CannotFlush(const std::string &s) : Exception(CANNOT_FLUSH, s) {}
    00173 };
    00174
    00175 //! error reported by the operating system
    00176 class CRYPTOPP_DLL OS_Error : public Exception
    00177 {
    00178 public:
    00179         OS_Error(ErrorType errorType, const std::string &s, const std::string& operation, int errorCode)
    00180                 : Exception(errorType, s), m_operation(operation), m_errorCode(errorCode) {}
    00181         ~OS_Error() throw() {}
    00182
    00183         // the operating system API that reported the error
    00184         const std::string & GetOperation() const {return m_operation;}
    00185         // the error code return by the operating system
    00186         int GetErrorCode() const {return m_errorCode;}
    00187
    00188 protected:
    00189         std::string m_operation;
    00190         int m_errorCode;
    00191 };
    00192
    00193 //! used to return decoding results
    00194 struct CRYPTOPP_DLL DecodingResult
    00195 {
    00196         explicit DecodingResult() : isValidCoding(false), messageLength(0) {}
    00197         explicit DecodingResult(size_t len) : isValidCoding(true), messageLength(len) {}
    00198
    00199         bool operator==(const DecodingResult &rhs) const {return isValidCoding == rhs.isValidCoding && messageLength == rhs.messageLength;}
    00200         bool operator!=(const DecodingResult &rhs) const {return !operator==(rhs);}
    00201
    00202         bool isValidCoding;
    00203         size_t messageLength;
    00204
    00205 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    00206         operator size_t() const {return isValidCoding ? messageLength : 0;}
    00207 #endif
    00208 };
    00209
    00210 //! interface for retrieving values given their names
    00211 /*! \note This class is used to safely pass a variable number of arbitrarily typed arguments to functions
    00212         and to read values from keys and crypto parameters.
    00213         \note To obtain an object that implements NameValuePairs for the purpose of parameter
    00214         passing, use the MakeParameters() function.
    00215         \note To get a value from NameValuePairs, you need to know the name and the type of the value.
    00216         Call GetValueNames() on a NameValuePairs object to obtain a list of value names that it supports.
    00217         Then look at the Name namespace documentation to see what the type of each value is, or
    00218         alternatively, call GetIntValue() with the value name, and if the type is not int, a
    00219         ValueTypeMismatch exception will be thrown and you can get the actual type from the exception object.
    00220 */
    00221 class CRYPTOPP_NO_VTABLE NameValuePairs
    00222 {
    00223 public:
    00224         virtual ~NameValuePairs() {}
    00225
    00226         //! exception thrown when trying to retrieve a value using a different type than expected
    00227         class CRYPTOPP_DLL ValueTypeMismatch : public InvalidArgument
    00228         {
    00229         public:
    00230                 ValueTypeMismatch(const std::string &name, const std::type_info &stored, const std::type_info &retrieving)
    00231                         : InvalidArgument("NameValuePairs: type mismatch for '" + name + "', stored '" + stored.name() + "', trying to retrieve '" + retrieving.name() + "'")
    00232                         , m_stored(stored), m_retrieving(retrieving) {}
    00233
    00234                 const std::type_info & GetStoredTypeInfo() const {return m_stored;}
    00235                 const std::type_info & GetRetrievingTypeInfo() const {return m_retrieving;}
    00236
    00237         private:
    00238                 const std::type_info &m_stored;
    00239                 const std::type_info &m_retrieving;
    00240         };
    00241
    00242         //! get a copy of this object or a subobject of it
    00243         template <class T>
    00244         bool GetThisObject(T &object) const
    00245         {
    00246                 return GetValue((std::string("ThisObject:")+typeid(T).name()).c_str(), object);
    00247         }
    00248
    00249         //! get a pointer to this object, as a pointer to T
    00250         template <class T>
    00251         bool GetThisPointer(T *&p) const
    00252         {
    00253                 return GetValue((std::string("ThisPointer:")+typeid(T).name()).c_str(), p);
    00254         }
    00255
    00256         //! get a named value, returns true if the name exists
    00257         template <class T>
    00258         bool GetValue(const char *name, T &value) const
    00259         {
    00260                 return GetVoidValue(name, typeid(T), &value);
    00261         }
    00262
    00263         //! get a named value, returns the default if the name doesn't exist
    00264         template <class T>
    00265         T GetValueWithDefault(const char *name, T defaultValue) const
    00266         {
    00267                 GetValue(name, defaultValue);
    00268                 return defaultValue;
    00269         }
    00270
    00271         //! get a list of value names that can be retrieved
    00272         CRYPTOPP_DLL std::string GetValueNames() const
    00273                 {std::string result; GetValue("ValueNames", result); return result;}
    00274
    00275         //! get a named value with type int
    00276         /*! used to ensure we don't accidentally try to get an unsigned int
    00277                 or some other type when we mean int (which is the most common case) */
    00278         CRYPTOPP_DLL bool GetIntValue(const char *name, int &value) const
    00279                 {return GetValue(name, value);}
    00280
    00281         //! get a named value with type int, with default
    00282         CRYPTOPP_DLL int GetIntValueWithDefault(const char *name, int defaultValue) const
    00283                 {return GetValueWithDefault(name, defaultValue);}
    00284
    00285         //! used by derived classes to check for type mismatch
    00286         CRYPTOPP_DLL static void CRYPTOPP_API ThrowIfTypeMismatch(const char *name, const std::type_info &stored, const std::type_info &retrieving)
    00287                 {if (stored != retrieving) throw ValueTypeMismatch(name, stored, retrieving);}
    00288
    00289         template <class T>
    00290         void GetRequiredParameter(const char *className, const char *name, T &value) const
    00291         {
    00292                 if (!GetValue(name, value))
    00293                         throw InvalidArgument(std::string(className) + ": missing required parameter '" + name + "'");
    00294         }
    00295
    00296         CRYPTOPP_DLL void GetRequiredIntParameter(const char *className, const char *name, int &value) const
    00297         {
    00298                 if (!GetIntValue(name, value))
    00299                         throw InvalidArgument(std::string(className) + ": missing required parameter '" + name + "'");
    00300         }
    00301
    00302         //! to be implemented by derived classes, users should use one of the above functions instead
    00303         CRYPTOPP_DLL virtual bool GetVoidValue(const char *name, const std::type_info &valueType, void *pValue) const =0;
    00304 };
    00305
    00306 //! namespace containing value name definitions
    00307 /*!     value names, types and semantics:
    00308
    00309         ThisObject:ClassName (ClassName, copy of this object or a subobject)
    00310         ThisPointer:ClassName (const ClassName *, pointer to this object or a subobject)
    00311 */
    00312 DOCUMENTED_NAMESPACE_BEGIN(Name)
    00313 // more names defined in argnames.h
    00314 DOCUMENTED_NAMESPACE_END
    00315
    00316 //! empty set of name-value pairs
    00317 class CRYPTOPP_DLL NullNameValuePairs : public NameValuePairs
    00318 {
    00319 public:
    00320         bool GetVoidValue(const char *name, const std::type_info &valueType, void *pValue) const {return false;}
    00321 };
    00322
    00323 //! _
    00324 extern CRYPTOPP_DLL const NullNameValuePairs g_nullNameValuePairs;
    00325
    00326 // ********************************************************
    00327
    00328 //! interface for cloning objects, this is not implemented by most classes yet
    00329 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Clonable
    00330 {
    00331 public:
    00332         virtual ~Clonable() {}
    00333         //! this is not implemented by most classes yet
    00334         virtual Clonable* Clone() const {throw NotImplemented("Clone() is not implemented yet.");}      // TODO: make this =0
    00335 };
    00336
    00337 //! interface for all crypto algorithms
    00338
    00339 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE Algorithm : public Clonable
    00340 {
    00341 public:
    00342         /*! When FIPS 140-2 compliance is enabled and checkSelfTestStatus == true,
    00343                 this constructor throws SelfTestFailure if the self test hasn't been run or fails. */
    00344         Algorithm(bool checkSelfTestStatus = true);
    00345         //! returns name of this algorithm, not universally implemented yet
    00346         virtual std::string AlgorithmName() const {return "unknown";}
    00347 };
    00348
    00349 //! keying interface for crypto algorithms that take byte strings as keys
    00350
    00351 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE SimpleKeyingInterface
    00352 {
    00353 public:
    00354         //! returns smallest valid key length in bytes */
    00355         virtual size_t MinKeyLength() const =0;
    00356         //! returns largest valid key length in bytes */
    00357         virtual size_t MaxKeyLength() const =0;
    00358         //! returns default (recommended) key length in bytes */
    00359         virtual size_t DefaultKeyLength() const =0;
    00360
    00361         //! returns the smallest valid key length in bytes that is >= min(n, GetMaxKeyLength())
    00362         virtual size_t GetValidKeyLength(size_t n) const =0;
    00363
    00364         //! returns whether n is a valid key length
    00365         virtual bool IsValidKeyLength(size_t n) const
    00366                 {return n == GetValidKeyLength(n);}
    00367
    00368         //! set or reset the key of this object
    00369         /*! \param params is used to specify Rounds, BlockSize, etc */
    00370         virtual void SetKey(const byte *key, size_t length, const NameValuePairs &params = g_nullNameValuePairs);
    00371
    00372         //! calls SetKey() with an NameValuePairs object that just specifies "Rounds"
    00373         void SetKeyWithRounds(const byte *key, size_t length, int rounds);
    00374
    00375         //! calls SetKey() with an NameValuePairs object that just specifies "IV"
    00376         void SetKeyWithIV(const byte *key, size_t length, const byte *iv);
    00377
    00378         enum IV_Requirement {STRUCTURED_IV = 0, RANDOM_IV, UNPREDICTABLE_RANDOM_IV, INTERNALLY_GENERATED_IV, NOT_RESYNCHRONIZABLE};
    00379         //! returns the minimal requirement for secure IVs
    00380         virtual IV_Requirement IVRequirement() const =0;
    00381
    00382         //! returns whether this object can be resynchronized (i.e. supports initialization vectors)
    00383         /*! If this function returns true, and no IV is passed to SetKey() and CanUseStructuredIVs()==true, an IV of all 0's will be assumed. */
    00384         bool IsResynchronizable() const {return IVRequirement() < NOT_RESYNCHRONIZABLE;}
    00385         //! returns whether this object can use random IVs (in addition to ones returned by GetNextIV)
    00386         bool CanUseRandomIVs() const {return IVRequirement() <= UNPREDICTABLE_RANDOM_IV;}
    00387         //! returns whether this object can use random but possibly predictable IVs (in addition to ones returned by GetNextIV)
    00388         bool CanUsePredictableIVs() const {return IVRequirement() <= RANDOM_IV;}
    00389         //! returns whether this object can use structured IVs, for example a counter (in addition to ones returned by GetNextIV)
    00390         bool CanUseStructuredIVs() const {return IVRequirement() <= STRUCTURED_IV;}
    00391
    00392         //! returns size of IVs used by this object
    00393         virtual unsigned int IVSize() const {throw NotImplemented("SimpleKeyingInterface: this object doesn't support resynchronization");}
    00394         //! resynchronize with an IV
    00395         virtual void Resynchronize(const byte *IV) {throw NotImplemented("SimpleKeyingInterface: this object doesn't support resynchronization");}
    00396         //! get a secure IV for the next message
    00397         /*! This method should be called after you finish encrypting one message and are ready to start the next one.
    00398                 After calling it, you must call SetKey() or Resynchronize() before using this object again.
    00399                 This method is not implemented on decryption objects. */
    00400         virtual void GetNextIV(byte *IV) {throw NotImplemented("SimpleKeyingInterface: this object doesn't support GetNextIV()");}
    00401
    00402 protected:
    00403         virtual const Algorithm & GetAlgorithm() const =0;
    00404         virtual void UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs &params) =0;
    00405
    00406         void ThrowIfInvalidKeyLength(size_t length);
    00407         void ThrowIfResynchronizable();                 // to be called when no IV is passed
    00408         void ThrowIfInvalidIV(const byte *iv);  // check for NULL IV if it can't be used
    00409         const byte * GetIVAndThrowIfInvalid(const NameValuePairs &params);
    00410         inline void AssertValidKeyLength(size_t length) const
    00411                 {assert(IsValidKeyLength(length));}
    00412 };
    00413
    00414 //! interface for the data processing part of block ciphers
    00415
    00416 /*! Classes derived from BlockTransformation are block ciphers
    00417         in ECB mode (for example the DES::Encryption class), which are stateless,
    00418         and they can make assumptions about the memory alignment of their inputs and outputs.
    00419         These classes should not be used directly, but only in combination with
    00420         a mode class (see CipherModeDocumentation in modes.h).
    00421 */
    00422 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE BlockTransformation : public Algorithm
    00423 {
    00424 public:
    00425         //! encrypt or decrypt inBlock, xor with xorBlock, and write to outBlock
    00426         virtual void ProcessAndXorBlock(const byte *inBlock, const byte *xorBlock, byte *outBlock) const =0;
    00427
    00428         //! encrypt or decrypt one block
    00429         /*! \pre size of inBlock and outBlock == BlockSize() */
    00430         void ProcessBlock(const byte *inBlock, byte *outBlock) const
    00431                 {ProcessAndXorBlock(inBlock, NULL, outBlock);}
    00432
    00433         //! encrypt or decrypt one block in place
    00434         void ProcessBlock(byte *inoutBlock) const
    00435                 {ProcessAndXorBlock(inoutBlock, NULL, inoutBlock);}
    00436
    00437         //! block size of the cipher in bytes
    00438         virtual unsigned int BlockSize() const =0;
    00439
    00440         //! block pointers must be divisible by this
    00441         virtual unsigned int BlockAlignment() const {return 4;}
    00442
    00443         //! returns true if this is a permutation (i.e. there is an inverse transformation)
    00444         virtual bool IsPermutation() const {return true;}
    00445
    00446         //! returns true if this is an encryption object
    00447         virtual bool IsForwardTransformation() const =0;
    00448
    00449         //! return number of blocks that can be processed in parallel, for bit-slicing implementations
    00450         virtual unsigned int OptimalNumberOfParallelBlocks() const {return 1;}
    00451
    00452         //! encrypt or decrypt multiple blocks, for bit-slicing implementations
    00453         virtual void ProcessAndXorMultipleBlocks(const byte *inBlocks, const byte *xorBlocks, byte *outBlocks, size_t numberOfBlocks) const;
    00454
    00455         inline CipherDir GetCipherDirection() const {return IsForwardTransformation() ? ENCRYPTION : DECRYPTION;}
    00456 };
    00457
    00458 //! interface for the data processing part of stream ciphers
    00459
    00460 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE StreamTransformation : public Algorithm
    00461 {
    00462 public:
    00463         //! return a reference to this object,
    00464         /*! This function is useful for passing a temporary StreamTransformation object to a
    00465                 function that takes a non-const reference. */
    00466         StreamTransformation& Ref() {return *this;}
    00467
    00468         //! returns block size, if input must be processed in blocks, otherwise 1
    00469         virtual unsigned int MandatoryBlockSize() const {return 1;}
    00470
    00471         //! returns the input block size that is most efficient for this cipher
    00472         /*! \note optimal input length is n * OptimalBlockSize() - GetOptimalBlockSizeUsed() for any n > 0 */
    00473         virtual unsigned int OptimalBlockSize() const {return MandatoryBlockSize();}
    00474         //! returns how much of the current block is used up
    00475         virtual unsigned int GetOptimalBlockSizeUsed() const {return 0;}
    00476
    00477         //! returns how input should be aligned for optimal performance
    00478         virtual unsigned int OptimalDataAlignment() const {return 1;}
    00479
    00480         //! encrypt or decrypt an array of bytes of specified length
    00481         /*! \note either inString == outString, or they don't overlap */
    00482         virtual void ProcessData(byte *outString, const byte *inString, size_t length) =0;
    00483
    00484         //! for ciphers where the last block of data is special, encrypt or decrypt the last block of data
    00485         /*! For now the only use of this function is for CBC-CTS mode. */
    00486         virtual void ProcessLastBlock(byte *outString, const byte *inString, size_t length);
    00487         //! returns the minimum size of the last block, 0 indicating the last block is not special
    00488         virtual unsigned int MinLastBlockSize() const {return 0;}
    00489
    00490         //! same as ProcessData(inoutString, inoutString, length)
    00491         inline void ProcessString(byte *inoutString, size_t length)
    00492                 {ProcessData(inoutString, inoutString, length);}
    00493         //! same as ProcessData(outString, inString, length)
    00494         inline void ProcessString(byte *outString, const byte *inString, size_t length)
    00495                 {ProcessData(outString, inString, length);}
    00496         //! implemented as {ProcessData(&input, &input, 1); return input;}
    00497         inline byte ProcessByte(byte input)
    00498                 {ProcessData(&input, &input, 1); return input;}
    00499
    00500         //! returns whether this cipher supports random access
    00501         virtual bool IsRandomAccess() const =0;
    00502         //! for random access ciphers, seek to an absolute position
    00503         virtual void Seek(lword n)
    00504         {
    00505                 assert(!IsRandomAccess());
    00506                 throw NotImplemented("StreamTransformation: this object doesn't support random access");
    00507         }
    00508
    00509         //! returns whether this transformation is self-inverting (e.g. xor with a keystream)
    00510         virtual bool IsSelfInverting() const =0;
    00511         //! returns whether this is an encryption object
    00512         virtual bool IsForwardTransformation() const =0;
    00513 };
    00514
    00515 //! interface for hash functions and data processing part of MACs
    00516
    00517 /*! HashTransformation objects are stateful.  They are created in an initial state,
    00518         change state as Update() is called, and return to the initial
    00519         state when Final() is called.  This interface allows a large message to
    00520         be hashed in pieces by calling Update() on each piece followed by
    00521         calling Final().
    00522 */
    00523 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE HashTransformation : public Algorithm
    00524 {
    00525 public:
    00526         //! return a reference to this object,
    00527         /*! This function is useful for passing a temporary HashTransformation object to a
    00528                 function that takes a non-const reference. */
    00529         HashTransformation& Ref() {return *this;}
    00530
    00531         //! process more input
    00532         virtual void Update(const byte *input, size_t length) =0;
    00533
    00534         //! request space to write input into
    00535         virtual byte * CreateUpdateSpace(size_t &size) {size=0; return NULL;}
    00536
    00537         //! compute hash for current message, then restart for a new message
    00538         /*!     \pre size of digest == DigestSize(). */
    00539         virtual void Final(byte *digest)
    00540                 {TruncatedFinal(digest, DigestSize());}
    00541
    00542         //! discard the current state, and restart with a new message
    00543         virtual void Restart()
    00544                 {TruncatedFinal(NULL, 0);}
    00545
    00546         //! size of the hash returned by Final()
    00547         virtual unsigned int DigestSize() const =0;
    00548
    00549         //! block size of underlying compression function, or 0 if not block based
    00550         virtual unsigned int BlockSize() const {return 0;}
    00551
    00552         //! input to Update() should have length a multiple of this for optimal speed
    00553         virtual unsigned int OptimalBlockSize() const {return 1;}
    00554
    00555         //! returns how input should be aligned for optimal performance
    00556         virtual unsigned int OptimalDataAlignment() const {return 1;}
    00557
    00558         //! use this if your input is in one piece and you don't want to call Update() and Final() separately
    00559         virtual void CalculateDigest(byte *digest, const byte *input, size_t length)
    00560                 {Update(input, length); Final(digest);}
    00561
    00562         //! verify that digest is a valid digest for the current message, then reinitialize the object
    00563         /*! Default implementation is to call Final() and do a bitwise comparison
    00564                 between its output and digest. */
    00565         virtual bool Verify(const byte *digest)
    00566                 {return TruncatedVerify(digest, DigestSize());}
    00567
    00568         //! use this if your input is in one piece and you don't want to call Update() and Verify() separately
    00569         virtual bool VerifyDigest(const byte *digest, const byte *input, size_t length)
    00570                 {Update(input, length); return Verify(digest);}
    00571
    00572         //! truncated version of Final()
    00573         virtual void TruncatedFinal(byte *digest, size_t digestSize) =0;
    00574
    00575         //! truncated version of CalculateDigest()
    00576         virtual void CalculateTruncatedDigest(byte *digest, size_t digestSize, const byte *input, size_t length)
    00577                 {Update(input, length); TruncatedFinal(digest, digestSize);}
    00578
    00579         //! truncated version of Verify()
    00580         virtual bool TruncatedVerify(const byte *digest, size_t digestLength);
    00581
    00582         //! truncated version of VerifyDigest()
    00583         virtual bool VerifyTruncatedDigest(const byte *digest, size_t digestLength, const byte *input, size_t length)
    00584                 {Update(input, length); return TruncatedVerify(digest, digestLength);}
    00585
    00586 protected:
    00587         void ThrowIfInvalidTruncatedSize(size_t size) const;
    00588 };
    00589
    00590 typedef HashTransformation HashFunction;
    00591
    00592 template <class T>
    00593 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE SimpleKeyedTransformation : public T, public SimpleKeyingInterface
    00594 {
    00595 protected:
    00596         const Algorithm & GetAlgorithm() const {return *this;}
    00597 };
    00598
    00599 #ifdef CRYPTOPP_DOXYGEN_PROCESSING
    00600 //! interface for one direction (encryption or decryption) of a block cipher
    00601 /*! \note These objects usually should not be used directly. See BlockTransformation for more details. */
    00602 class BlockCipher : public BlockTransformation, public SimpleKeyingInterface {};
    00603 //! interface for one direction (encryption or decryption) of a stream cipher or cipher mode
    00604 class SymmetricCipher : public StreamTransformation, public SimpleKeyingInterface {};
    00605 //! interface for message authentication codes
    00606 class MessageAuthenticationCode : public HashTransformation, public SimpleKeyingInterface {};
    00607 #else
    00608 typedef SimpleKeyedTransformation<BlockTransformation> BlockCipher;
    00609 typedef SimpleKeyedTransformation<StreamTransformation> SymmetricCipher;
    00610 typedef SimpleKeyedTransformation<HashTransformation> MessageAuthenticationCode;
    00611 #endif
    00612
    00613 CRYPTOPP_DLL_TEMPLATE_CLASS SimpleKeyedTransformation<BlockTransformation>;
    00614 CRYPTOPP_DLL_TEMPLATE_CLASS SimpleKeyedTransformation<StreamTransformation>;
    00615 CRYPTOPP_DLL_TEMPLATE_CLASS SimpleKeyedTransformation<HashTransformation>;
    00616
    00617 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    00618 typedef SymmetricCipher StreamCipher;
    00619 #endif
    00620
    00621 //! interface for random number generators
    00622 /*! All return values are uniformly distributed over the range specified.
    00623 */
    00624 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE RandomNumberGenerator : public Algorithm
    00625 {
    00626 public:
    00627         //! generate new random byte and return it
    00628         virtual byte GenerateByte() =0;
    00629
    00630         //! generate new random bit and return it
    00631         /*! Default implementation is to call GenerateByte() and return its parity. */
    00632         virtual unsigned int GenerateBit();
    00633
    00634         //! generate a random 32 bit word in the range min to max, inclusive
    00635         virtual word32 GenerateWord32(word32 a=0, word32 b=0xffffffffL);
    00636
    00637         //! generate random array of bytes
    00638         /*! Default implementation is to call GenerateByte() size times. */
    00639         virtual void GenerateBlock(byte *output, size_t size);
    00640
    00641         //! generate and discard n bytes
    00642         /*! Default implementation is to call GenerateByte() n times. */
    00643         virtual void DiscardBytes(size_t n);
    00644
    00645         //! randomly shuffle the specified array, resulting permutation is uniformly distributed
    00646         template <class IT> void Shuffle(IT begin, IT end)
    00647         {
    00648                 for (; begin != end; ++begin)
    00649                         std::iter_swap(begin, begin + GenerateWord32(0, end-begin-1));
    00650         }
    00651
    00652 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    00653         byte GetByte() {return GenerateByte();}
    00654         unsigned int GetBit() {return GenerateBit();}
    00655         word32 GetLong(word32 a=0, word32 b=0xffffffffL) {return GenerateWord32(a, b);}
    00656         word16 GetShort(word16 a=0, word16 b=0xffff) {return (word16)GenerateWord32(a, b);}
    00657         void GetBlock(byte *output, size_t size) {GenerateBlock(output, size);}
    00658 #endif
    00659 };
    00660
    00661 //! returns a reference that can be passed to functions that ask for a RNG but doesn't actually use it
    00662 CRYPTOPP_DLL RandomNumberGenerator & CRYPTOPP_API NullRNG();
    00663
    00664 class WaitObjectContainer;
    00665 class CallStack;
    00666
    00667 //! interface for objects that you can wait for
    00668
    00669 class CRYPTOPP_NO_VTABLE Waitable
    00670 {
    00671 public:
    00672         //! maximum number of wait objects that this object can return
    00673         virtual unsigned int GetMaxWaitObjectCount() const =0;
    00674         //! put wait objects into container
    00675         /*! \param callStack is used for tracing no wait loops, example:
    00676                      something.GetWaitObjects(c, CallStack("my func after X", 0));
    00677                            - or in an outer GetWaitObjects() method that itself takes a callStack parameter:
    00678                              innerThing.GetWaitObjects(c, CallStack("MyClass::GetWaitObjects at X", &callStack)); */
    00679         virtual void GetWaitObjects(WaitObjectContainer &container, CallStack const& callStack) =0;
    00680         //! wait on this object
    00681         /*! same as creating an empty container, calling GetWaitObjects(), and calling Wait() on the container */
    00682         bool Wait(unsigned long milliseconds, CallStack const& callStack);
    00683 };
    00684
    00685 //! interface for buffered transformations
    00686
    00687 /*! BufferedTransformation is a generalization of BlockTransformation,
    00688         StreamTransformation, and HashTransformation.
    00689
    00690         A buffered transformation is an object that takes a stream of bytes
    00691         as input (this may be done in stages), does some computation on them, and
    00692         then places the result into an internal buffer for later retrieval.  Any
    00693         partial result already in the output buffer is not modified by further
    00694         input.
    00695
    00696         If a method takes a "blocking" parameter, and you
    00697         pass "false" for it, the method will return before all input has been processed if
    00698         the input cannot be processed without waiting (for network buffers to become available, for example).
    00699         In this case the method will return true
    00700         or a non-zero integer value. When this happens you must continue to call the method with the same
    00701         parameters until it returns false or zero, before calling any other method on it or
    00702         attached BufferedTransformation. The integer return value in this case is approximately
    00703         the number of bytes left to be processed, and can be used to implement a progress bar.
    00704
    00705         For functions that take a "propagation" parameter, propagation != 0 means pass on the signal to attached
    00706         BufferedTransformation objects, with propagation decremented at each step until it reaches 0.
    00707         -1 means unlimited propagation.
    00708
    00709         \nosubgrouping
    00710 */
    00711 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE BufferedTransformation : public Algorithm, public Waitable
    00712 {
    00713 public:
    00714         // placed up here for CW8
    00715         static const std::string NULL_CHANNEL;  // the empty string ""
    00716
    00717         BufferedTransformation() : Algorithm(false) {}
    00718
    00719         //! return a reference to this object
    00720         /*! This function is useful for passing a temporary BufferedTransformation object to a
    00721                 function that takes a non-const reference. */
    00722         BufferedTransformation& Ref() {return *this;}
    00723
    00724         //!     \name INPUT
    00725         //@{
    00726                 //! input a byte for processing
    00727                 size_t Put(byte inByte, bool blocking=true)
    00728                         {return Put(&inByte, 1, blocking);}
    00729                 //! input multiple bytes
    00730                 size_t Put(const byte *inString, size_t length, bool blocking=true)
    00731                         {return Put2(inString, length, 0, blocking);}
    00732
    00733                 //! input a 16-bit word
    00734                 size_t PutWord16(word16 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true);
    00735                 //! input a 32-bit word
    00736                 size_t PutWord32(word32 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true);
    00737
    00738                 //! request space which can be written into by the caller, and then used as input to Put()
    00739                 /*! \param size is requested size (as a hint) for input, and size of the returned space for output */
    00740                 /*! \note The purpose of this method is to help avoid doing extra memory allocations. */
    00741                 virtual byte * CreatePutSpace(size_t &size) {size=0; return NULL;}
    00742
    00743                 virtual bool CanModifyInput() const {return false;}
    00744
    00745                 //! input multiple bytes that may be modified by callee
    00746                 size_t PutModifiable(byte *inString, size_t length, bool blocking=true)
    00747                         {return PutModifiable2(inString, length, 0, blocking);}
    00748
    00749                 bool MessageEnd(int propagation=-1, bool blocking=true)
    00750                         {return !!Put2(NULL, 0, propagation < 0 ? -1 : propagation+1, blocking);}
    00751                 size_t PutMessageEnd(const byte *inString, size_t length, int propagation=-1, bool blocking=true)
    00752                         {return Put2(inString, length, propagation < 0 ? -1 : propagation+1, blocking);}
    00753
    00754                 //! input multiple bytes for blocking or non-blocking processing
    00755                 /*! \param messageEnd means how many filters to signal MessageEnd to, including this one */
    00756                 virtual size_t Put2(const byte *inString, size_t length, int messageEnd, bool blocking) =0;
    00757                 //! input multiple bytes that may be modified by callee for blocking or non-blocking processing
    00758                 /*! \param messageEnd means how many filters to signal MessageEnd to, including this one */
    00759                 virtual size_t PutModifiable2(byte *inString, size_t length, int messageEnd, bool blocking)
    00760                         {return Put2(inString, length, messageEnd, blocking);}
    00761
    00762                 //! thrown by objects that have not implemented nonblocking input processing
    00763                 struct BlockingInputOnly : public NotImplemented
    00764                         {BlockingInputOnly(const std::string &s) : NotImplemented(s + ": Nonblocking input is not implemented by this object.") {}};
    00765         //@}
    00766
    00767         //!     \name WAITING
    00768         //@{
    00769                 unsigned int GetMaxWaitObjectCount() const;
    00770                 void GetWaitObjects(WaitObjectContainer &container, CallStack const& callStack);
    00771         //@}
    00772
    00773         //!     \name SIGNALS
    00774         //@{
    00775                 virtual void IsolatedInitialize(const NameValuePairs &parameters) {throw NotImplemented("BufferedTransformation: this object can't be reinitialized");}
    00776                 virtual bool IsolatedFlush(bool hardFlush, bool blocking) =0;
    00777                 virtual bool IsolatedMessageSeriesEnd(bool blocking) {return false;}
    00778
    00779                 //! initialize or reinitialize this object
    00780                 virtual void Initialize(const NameValuePairs &parameters=g_nullNameValuePairs, int propagation=-1);
    00781                 //! flush buffered input and/or output
    00782                 /*! \param hardFlush is used to indicate whether all data should be flushed
    00783                         \note Hard flushes must be used with care. It means try to process and output everything, even if
    00784                         there may not be enough data to complete the action. For example, hard flushing a HexDecoder would
    00785                         cause an error if you do it after inputing an odd number of hex encoded characters.
    00786                         For some types of filters, for example ZlibDecompressor, hard flushes can only
    00787                         be done at "synchronization points". These synchronization points are positions in the data
    00788                         stream that are created by hard flushes on the corresponding reverse filters, in this
    00789                         example ZlibCompressor. This is useful when zlib compressed data is moved across a
    00790                         network in packets and compression state is preserved across packets, as in the ssh2 protocol.
    00791                 */
    00792                 virtual bool Flush(bool hardFlush, int propagation=-1, bool blocking=true);
    00793                 //! mark end of a series of messages
    00794                 /*! There should be a MessageEnd immediately before MessageSeriesEnd. */
    00795                 virtual bool MessageSeriesEnd(int propagation=-1, bool blocking=true);
    00796
    00797                 //! set propagation of automatically generated and transferred signals
    00798                 /*! propagation == 0 means do not automaticly generate signals */
    00799                 virtual void SetAutoSignalPropagation(int propagation) {}
    00800
    00801                 //!
    00802                 virtual int GetAutoSignalPropagation() const {return 0;}
    00803 public:
    00804
    00805 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    00806                 void Close() {MessageEnd();}
    00807 #endif
    00808         //@}
    00809
    00810         //!     \name RETRIEVAL OF ONE MESSAGE
    00811         //@{
    00812                 //! returns number of bytes that is currently ready for retrieval
    00813                 /*! All retrieval functions return the actual number of bytes
    00814                         retrieved, which is the lesser of the request number and
    00815                         MaxRetrievable(). */
    00816                 virtual lword MaxRetrievable() const;
    00817
    00818                 //! returns whether any bytes are currently ready for retrieval
    00819                 virtual bool AnyRetrievable() const;
    00820
    00821                 //! try to retrieve a single byte
    00822                 virtual size_t Get(byte &outByte);
    00823                 //! try to retrieve multiple bytes
    00824                 virtual size_t Get(byte *outString, size_t getMax);
    00825
    00826                 //! peek at the next byte without removing it from the output buffer
    00827                 virtual size_t Peek(byte &outByte) const;
    00828                 //! peek at multiple bytes without removing them from the output buffer
    00829                 virtual size_t Peek(byte *outString, size_t peekMax) const;
    00830
    00831                 //! try to retrieve a 16-bit word
    00832                 size_t GetWord16(word16 &value, ByteOrder order=BIG_ENDIAN_ORDER);
    00833                 //! try to retrieve a 32-bit word
    00834                 size_t GetWord32(word32 &value, ByteOrder order=BIG_ENDIAN_ORDER);
    00835
    00836                 //! try to peek at a 16-bit word
    00837                 size_t PeekWord16(word16 &value, ByteOrder order=BIG_ENDIAN_ORDER) const;
    00838                 //! try to peek at a 32-bit word
    00839                 size_t PeekWord32(word32 &value, ByteOrder order=BIG_ENDIAN_ORDER) const;
    00840
    00841                 //! move transferMax bytes of the buffered output to target as input
    00842                 lword TransferTo(BufferedTransformation &target, lword transferMax=LWORD_MAX, const std::string &channel=NULL_CHANNEL)
    00843                         {TransferTo2(target, transferMax, channel); return transferMax;}
    00844
    00845                 //! discard skipMax bytes from the output buffer
    00846                 virtual lword Skip(lword skipMax=LWORD_MAX);
    00847
    00848                 //! copy copyMax bytes of the buffered output to target as input
    00849                 lword CopyTo(BufferedTransformation &target, lword copyMax=LWORD_MAX, const std::string &channel=NULL_CHANNEL) const
    00850                         {return CopyRangeTo(target, 0, copyMax, channel);}
    00851
    00852                 //! copy copyMax bytes of the buffered output, starting at position (relative to current position), to target as input
    00853                 lword CopyRangeTo(BufferedTransformation &target, lword position, lword copyMax=LWORD_MAX, const std::string &channel=NULL_CHANNEL) const
    00854                         {lword i = position; CopyRangeTo2(target, i, i+copyMax, channel); return i-position;}
    00855
    00856 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    00857                 unsigned long MaxRetrieveable() const {return MaxRetrievable();}
    00858 #endif
    00859         //@}
    00860
    00861         //!     \name RETRIEVAL OF MULTIPLE MESSAGES
    00862         //@{
    00863                 //!
    00864                 virtual lword TotalBytesRetrievable() const;
    00865                 //! number of times MessageEnd() has been received minus messages retrieved or skipped
    00866                 virtual unsigned int NumberOfMessages() const;
    00867                 //! returns true if NumberOfMessages() > 0
    00868                 virtual bool AnyMessages() const;
    00869                 //! start retrieving the next message
    00870                 /*!
    00871                         Returns false if no more messages exist or this message
    00872                         is not completely retrieved.
    00873                 */
    00874                 virtual bool GetNextMessage();
    00875                 //! skip count number of messages
    00876                 virtual unsigned int SkipMessages(unsigned int count=UINT_MAX);
    00877                 //!
    00878                 unsigned int TransferMessagesTo(BufferedTransformation &target, unsigned int count=UINT_MAX, const std::string &channel=NULL_CHANNEL)
    00879                         {TransferMessagesTo2(target, count, channel); return count;}
    00880                 //!
    00881                 unsigned int CopyMessagesTo(BufferedTransformation &target, unsigned int count=UINT_MAX, const std::string &channel=NULL_CHANNEL) const;
    00882
    00883                 //!
    00884                 virtual void SkipAll();
    00885                 //!
    00886                 void TransferAllTo(BufferedTransformation &target, const std::string &channel=NULL_CHANNEL)
    00887                         {TransferAllTo2(target, channel);}
    00888                 //!
    00889                 void CopyAllTo(BufferedTransformation &target, const std::string &channel=NULL_CHANNEL) const;
    00890
    00891                 virtual bool GetNextMessageSeries() {return false;}
    00892                 virtual unsigned int NumberOfMessagesInThisSeries() const {return NumberOfMessages();}
    00893                 virtual unsigned int NumberOfMessageSeries() const {return 0;}
    00894         //@}
    00895
    00896         //!     \name NON-BLOCKING TRANSFER OF OUTPUT
    00897         //@{
    00898                 //! upon return, byteCount contains number of bytes that have finished being transfered, and returns the number of bytes left in the current transfer block
    00899                 virtual size_t TransferTo2(BufferedTransformation &target, lword &byteCount, const std::string &channel=NULL_CHANNEL, bool blocking=true) =0;
    00900                 //! 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
    00901                 virtual size_t CopyRangeTo2(BufferedTransformation &target, lword &begin, lword end=LWORD_MAX, const std::string &channel=NULL_CHANNEL, bool blocking=true) const =0;
    00902                 //! upon return, messageCount contains number of messages that have finished being transfered, and returns the number of bytes left in the current transfer block
    00903                 size_t TransferMessagesTo2(BufferedTransformation &target, unsigned int &messageCount, const std::string &channel=NULL_CHANNEL, bool blocking=true);
    00904                 //! returns the number of bytes left in the current transfer block
    00905                 size_t TransferAllTo2(BufferedTransformation &target, const std::string &channel=NULL_CHANNEL, bool blocking=true);
    00906         //@}
    00907
    00908         //!     \name CHANNELS
    00909         //@{
    00910                 struct NoChannelSupport : public NotImplemented
    00911                         {NoChannelSupport() : NotImplemented("BufferedTransformation: this object doesn't support multiple channels") {}};
    00912
    00913                 size_t ChannelPut(const std::string &channel, byte inByte, bool blocking=true)
    00914                         {return ChannelPut(channel, &inByte, 1, blocking);}
    00915                 size_t ChannelPut(const std::string &channel, const byte *inString, size_t length, bool blocking=true)
    00916                         {return ChannelPut2(channel, inString, length, 0, blocking);}
    00917
    00918                 size_t ChannelPutModifiable(const std::string &channel, byte *inString, size_t length, bool blocking=true)
    00919                         {return ChannelPutModifiable2(channel, inString, length, 0, blocking);}
    00920
    00921                 size_t ChannelPutWord16(const std::string &channel, word16 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true);
    00922                 size_t ChannelPutWord32(const std::string &channel, word32 value, ByteOrder order=BIG_ENDIAN_ORDER, bool blocking=true);
    00923
    00924                 bool ChannelMessageEnd(const std::string &channel, int propagation=-1, bool blocking=true)
    00925                         {return !!ChannelPut2(channel, NULL, 0, propagation < 0 ? -1 : propagation+1, blocking);}
    00926                 size_t ChannelPutMessageEnd(const std::string &channel, const byte *inString, size_t length, int propagation=-1, bool blocking=true)
    00927                         {return ChannelPut2(channel, inString, length, propagation < 0 ? -1 : propagation+1, blocking);}
    00928
    00929                 virtual byte * ChannelCreatePutSpace(const std::string &channel, size_t &size);
    00930
    00931                 virtual size_t ChannelPut2(const std::string &channel, const byte *begin, size_t length, int messageEnd, bool blocking);
    00932                 virtual size_t ChannelPutModifiable2(const std::string &channel, byte *begin, size_t length, int messageEnd, bool blocking);
    00933
    00934                 virtual bool ChannelFlush(const std::string &channel, bool hardFlush, int propagation=-1, bool blocking=true);
    00935                 virtual bool ChannelMessageSeriesEnd(const std::string &channel, int propagation=-1, bool blocking=true);
    00936
    00937                 virtual void SetRetrievalChannel(const std::string &channel);
    00938         //@}
    00939
    00940         //!     \name ATTACHMENT
    00941         /*! Some BufferedTransformation objects (e.g. Filter objects)
    00942                 allow other BufferedTransformation objects to be attached. When
    00943                 this is done, the first object instead of buffering its output,
    00944                 sents that output to the attached object as input. The entire
    00945                 attachment chain is deleted when the anchor object is destructed.
    00946         */
    00947         //@{
    00948                 //! returns whether this object allows attachment
    00949                 virtual bool Attachable() {return false;}
    00950                 //! returns the object immediately attached to this object or NULL for no attachment
    00951                 virtual BufferedTransformation *AttachedTransformation() {assert(!Attachable()); return 0;}
    00952                 //!
    00953                 virtual const BufferedTransformation *AttachedTransformation() const
    00954                         {return const_cast<BufferedTransformation *>(this)->AttachedTransformation();}
    00955                 //! delete the current attachment chain and replace it with newAttachment
    00956                 virtual void Detach(BufferedTransformation *newAttachment = 0)
    00957                         {assert(!Attachable()); throw NotImplemented("BufferedTransformation: this object is not attachable");}
    00958                 //! add newAttachment to the end of attachment chain
    00959                 virtual void Attach(BufferedTransformation *newAttachment);
    00960         //@}
    00961
    00962 protected:
    00963         static int DecrementPropagation(int propagation)
    00964                 {return propagation != 0 ? propagation - 1 : 0;}
    00965
    00966 private:
    00967         byte m_buf[4];  // for ChannelPutWord16 and ChannelPutWord32, to ensure buffer isn't deallocated before non-blocking operation completes
    00968 };
    00969
    00970 //! returns a reference to a BufferedTransformation object that discards all input
    00971 BufferedTransformation & TheBitBucket();
    00972
    00973 //! interface for crypto material, such as public and private keys, and crypto parameters
    00974
    00975 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CryptoMaterial : public NameValuePairs
    00976 {
    00977 public:
    00978         //! exception thrown when invalid crypto material is detected
    00979         class CRYPTOPP_DLL InvalidMaterial : public InvalidDataFormat
    00980         {
    00981         public:
    00982                 explicit InvalidMaterial(const std::string &s) : InvalidDataFormat(s) {}
    00983         };
    00984
    00985         //! assign values from source to this object
    00986         /*! \note This function can be used to create a public key from a private key. */
    00987         virtual void AssignFrom(const NameValuePairs &source) =0;
    00988
    00989         //! check this object for errors
    00990         /*! \param level denotes the level of thoroughness:
    00991                 0 - using this object won't cause a crash or exception (rng is ignored)
    00992                 1 - this object will probably function (encrypt, sign, etc.) correctly (but may not check for weak keys and such)
    00993                 2 - make sure this object will function correctly, and do reasonable security checks
    00994                 3 - do checks that may take a long time
    00995                 \return true if the tests pass */
    00996         virtual bool Validate(RandomNumberGenerator &rng, unsigned int level) const =0;
    00997
    00998         //! throws InvalidMaterial if this object fails Validate() test
    00999         virtual void ThrowIfInvalid(RandomNumberGenerator &rng, unsigned int level) const
    01000                 {if (!Validate(rng, level)) throw InvalidMaterial("CryptoMaterial: this object contains invalid values");}
    01001
    01002 //      virtual std::vector<std::string> GetSupportedFormats(bool includeSaveOnly=false, bool includeLoadOnly=false);
    01003
    01004         //! save key into a BufferedTransformation
    01005         virtual void Save(BufferedTransformation &bt) const
    01006                 {throw NotImplemented("CryptoMaterial: this object does not support saving");}
    01007
    01008         //! load key from a BufferedTransformation
    01009         /*! \throws KeyingErr if decode fails
    01010                 \note Generally does not check that the key is valid.
    01011                         Call ValidateKey() or ThrowIfInvalidKey() to check that. */
    01012         virtual void Load(BufferedTransformation &bt)
    01013                 {throw NotImplemented("CryptoMaterial: this object does not support loading");}
    01014
    01015         //! \return whether this object supports precomputation
    01016         virtual bool SupportsPrecomputation() const {return false;}
    01017         //! do precomputation
    01018         /*! The exact semantics of Precompute() is varies, but
    01019                 typically it means calculate a table of n objects
    01020                 that can be used later to speed up computation. */
    01021         virtual void Precompute(unsigned int n)
    01022                 {assert(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation");}
    01023         //! retrieve previously saved precomputation
    01024         virtual void LoadPrecomputation(BufferedTransformation &storedPrecomputation)
    01025                 {assert(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation");}
    01026         //! save precomputation for later use
    01027         virtual void SavePrecomputation(BufferedTransformation &storedPrecomputation) const
    01028                 {assert(!SupportsPrecomputation()); throw NotImplemented("CryptoMaterial: this object does not support precomputation");}
    01029
    01030         // for internal library use
    01031         void DoQuickSanityCheck() const {ThrowIfInvalid(NullRNG(), 0);}
    01032 };
    01033
    01034 //! interface for generatable crypto material, such as private keys and crypto parameters
    01035
    01036 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE GeneratableCryptoMaterial : virtual public CryptoMaterial
    01037 {
    01038 public:
    01039         //! generate a random key or crypto parameters
    01040         /*! \throws KeyingErr if algorithm parameters are invalid, or if a key can't be generated
    01041                 (e.g., if this is a public key object) */
    01042         virtual void GenerateRandom(RandomNumberGenerator &rng, const NameValuePairs &params = g_nullNameValuePairs)
    01043                 {throw NotImplemented("GeneratableCryptoMaterial: this object does not support key/parameter generation");}
    01044
    01045         //! calls the above function with a NameValuePairs object that just specifies "KeySize"
    01046         void GenerateRandomWithKeySize(RandomNumberGenerator &rng, unsigned int keySize);
    01047 };
    01048
    01049 //! interface for public keys
    01050
    01051 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PublicKey : virtual public CryptoMaterial
    01052 {
    01053 };
    01054
    01055 //! interface for private keys
    01056
    01057 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PrivateKey : public GeneratableCryptoMaterial
    01058 {
    01059 };
    01060
    01061 //! interface for crypto prameters
    01062
    01063 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE CryptoParameters : public GeneratableCryptoMaterial
    01064 {
    01065 };
    01066
    01067 //! interface for asymmetric algorithms
    01068
    01069 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AsymmetricAlgorithm : public Algorithm
    01070 {
    01071 public:
    01072         //! returns a reference to the crypto material used by this object
    01073         virtual CryptoMaterial & AccessMaterial() =0;
    01074         //! returns a const reference to the crypto material used by this object
    01075         virtual const CryptoMaterial & GetMaterial() const =0;
    01076
    01077         //! for backwards compatibility, calls AccessMaterial().Load(bt)
    01078         void BERDecode(BufferedTransformation &bt)
    01079                 {AccessMaterial().Load(bt);}
    01080         //! for backwards compatibility, calls GetMaterial().Save(bt)
    01081         void DEREncode(BufferedTransformation &bt) const
    01082                 {GetMaterial().Save(bt);}
    01083 };
    01084
    01085 //! interface for asymmetric algorithms using public keys
    01086
    01087 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PublicKeyAlgorithm : public AsymmetricAlgorithm
    01088 {
    01089 public:
    01090         // VC60 workaround: no co-variant return type
    01091         CryptoMaterial & AccessMaterial() {return AccessPublicKey();}
    01092         const CryptoMaterial & GetMaterial() const {return GetPublicKey();}
    01093
    01094         virtual PublicKey & AccessPublicKey() =0;
    01095         virtual const PublicKey & GetPublicKey() const {return const_cast<PublicKeyAlgorithm *>(this)->AccessPublicKey();}
    01096 };
    01097
    01098 //! interface for asymmetric algorithms using private keys
    01099
    01100 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PrivateKeyAlgorithm : public AsymmetricAlgorithm
    01101 {
    01102 public:
    01103         CryptoMaterial & AccessMaterial() {return AccessPrivateKey();}
    01104         const CryptoMaterial & GetMaterial() const {return GetPrivateKey();}
    01105
    01106         virtual PrivateKey & AccessPrivateKey() =0;
    01107         virtual const PrivateKey & GetPrivateKey() const {return const_cast<PrivateKeyAlgorithm *>(this)->AccessPrivateKey();}
    01108 };
    01109
    01110 //! interface for key agreement algorithms
    01111
    01112 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE KeyAgreementAlgorithm : public AsymmetricAlgorithm
    01113 {
    01114 public:
    01115         CryptoMaterial & AccessMaterial() {return AccessCryptoParameters();}
    01116         const CryptoMaterial & GetMaterial() const {return GetCryptoParameters();}
    01117
    01118         virtual CryptoParameters & AccessCryptoParameters() =0;
    01119         virtual const CryptoParameters & GetCryptoParameters() const {return const_cast<KeyAgreementAlgorithm *>(this)->AccessCryptoParameters();}
    01120 };
    01121
    01122 //! interface for public-key encryptors and decryptors
    01123
    01124 /*! This class provides an interface common to encryptors and decryptors
    01125         for querying their plaintext and ciphertext lengths.
    01126 */
    01127 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_CryptoSystem
    01128 {
    01129 public:
    01130         virtual ~PK_CryptoSystem() {}
    01131
    01132         //! maximum length of plaintext for a given ciphertext length
    01133         /*! \note This function returns 0 if ciphertextLength is not valid (too long or too short). */
    01134         virtual size_t MaxPlaintextLength(size_t ciphertextLength) const =0;
    01135
    01136         //! calculate length of ciphertext given length of plaintext
    01137         /*! \note This function returns 0 if plaintextLength is not valid (too long). */
    01138         virtual size_t CiphertextLength(size_t plaintextLength) const =0;
    01139
    01140         //! this object supports the use of the parameter with the given name
    01141         /*! some possible parameter names: EncodingParameters, KeyDerivationParameters */
    01142         virtual bool ParameterSupported(const char *name) const =0;
    01143
    01144         //! return fixed ciphertext length, if one exists, otherwise return 0
    01145         /*! \note "Fixed" here means length of ciphertext does not depend on length of plaintext.
    01146                 It usually does depend on the key length. */
    01147         virtual size_t FixedCiphertextLength() const {return 0;}
    01148
    01149         //! return maximum plaintext length given the fixed ciphertext length, if one exists, otherwise return 0
    01150         virtual size_t FixedMaxPlaintextLength() const {return 0;}
    01151
    01152 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    01153         size_t MaxPlainTextLength(size_t cipherTextLength) const {return MaxPlaintextLength(cipherTextLength);}
    01154         size_t CipherTextLength(size_t plainTextLength) const {return CiphertextLength(plainTextLength);}
    01155 #endif
    01156 };
    01157
    01158 //! interface for public-key encryptors
    01159 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Encryptor : public PK_CryptoSystem, public PublicKeyAlgorithm
    01160 {
    01161 public:
    01162         //! exception thrown when trying to encrypt plaintext of invalid length
    01163         class CRYPTOPP_DLL InvalidPlaintextLength : public Exception
    01164         {
    01165         public:
    01166                 InvalidPlaintextLength() : Exception(OTHER_ERROR, "PK_Encryptor: invalid plaintext length") {}
    01167         };
    01168
    01169         //! encrypt a byte string
    01170         /*! \pre CiphertextLength(plaintextLength) != 0 (i.e., plaintext isn't too long)
    01171                 \pre size of ciphertext == CiphertextLength(plaintextLength)
    01172         */
    01173         virtual void Encrypt(RandomNumberGenerator &rng,
    01174                 const byte *plaintext, size_t plaintextLength,
    01175                 byte *ciphertext, const NameValuePairs &parameters = g_nullNameValuePairs) const =0;
    01176
    01177         //! create a new encryption filter
    01178         /*! \note The caller is responsible for deleting the returned pointer.
    01179                 \note Encoding parameters should be passed in the "EP" channel.
    01180         */
    01181         virtual BufferedTransformation * CreateEncryptionFilter(RandomNumberGenerator &rng,
    01182                 BufferedTransformation *attachment=NULL, const NameValuePairs &parameters = g_nullNameValuePairs) const;
    01183 };
    01184
    01185 //! interface for public-key decryptors
    01186
    01187 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Decryptor : public PK_CryptoSystem, public PrivateKeyAlgorithm
    01188 {
    01189 public:
    01190         //! decrypt a byte string, and return the length of plaintext
    01191         /*! \pre size of plaintext == MaxPlaintextLength(ciphertextLength) bytes.
    01192                 \return the actual length of the plaintext, indication that decryption failed.
    01193         */
    01194         virtual DecodingResult Decrypt(RandomNumberGenerator &rng,
    01195                 const byte *ciphertext, size_t ciphertextLength,
    01196                 byte *plaintext, const NameValuePairs &parameters = g_nullNameValuePairs) const =0;
    01197
    01198         //! create a new decryption filter
    01199         /*! \note caller is responsible for deleting the returned pointer
    01200         */
    01201         virtual BufferedTransformation * CreateDecryptionFilter(RandomNumberGenerator &rng,
    01202                 BufferedTransformation *attachment=NULL, const NameValuePairs &parameters = g_nullNameValuePairs) const;
    01203
    01204         //! decrypt a fixed size ciphertext
    01205         DecodingResult FixedLengthDecrypt(RandomNumberGenerator &rng, const byte *ciphertext, byte *plaintext, const NameValuePairs &parameters = g_nullNameValuePairs) const
    01206                 {return Decrypt(rng, ciphertext, FixedCiphertextLength(), plaintext, parameters);}
    01207 };
    01208
    01209 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    01210 typedef PK_CryptoSystem PK_FixedLengthCryptoSystem;
    01211 typedef PK_Encryptor PK_FixedLengthEncryptor;
    01212 typedef PK_Decryptor PK_FixedLengthDecryptor;
    01213 #endif
    01214
    01215 //! interface for public-key signers and verifiers
    01216
    01217 /*! This class provides an interface common to signers and verifiers
    01218         for querying scheme properties.
    01219 */
    01220 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_SignatureScheme
    01221 {
    01222 public:
    01223         //! invalid key exception, may be thrown by any function in this class if the private or public key has a length that can't be used
    01224         class CRYPTOPP_DLL InvalidKeyLength : public Exception
    01225         {
    01226         public:
    01227                 InvalidKeyLength(const std::string &message) : Exception(OTHER_ERROR, message) {}
    01228         };
    01229
    01230         //! key too short exception, may be thrown by any function in this class if the private or public key is too short to sign or verify anything
    01231         class CRYPTOPP_DLL KeyTooShort : public InvalidKeyLength
    01232         {
    01233         public:
    01234                 KeyTooShort() : InvalidKeyLength("PK_Signer: key too short for this signature scheme") {}
    01235         };
    01236
    01237         virtual ~PK_SignatureScheme() {}
    01238
    01239         //! signature length if it only depends on the key, otherwise 0
    01240         virtual size_t SignatureLength() const =0;
    01241
    01242         //! maximum signature length produced for a given length of recoverable message part
    01243         virtual size_t MaxSignatureLength(size_t recoverablePartLength = 0) const {return SignatureLength();}
    01244
    01245         //! length of longest message that can be recovered, or 0 if this signature scheme does not support message recovery
    01246         virtual size_t MaxRecoverableLength() const =0;
    01247
    01248         //! 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
    01249         virtual size_t MaxRecoverableLengthFromSignatureLength(size_t signatureLength) const =0;
    01250
    01251         //! requires a random number generator to sign
    01252         /*! if this returns false, NullRNG() can be passed to functions that take RandomNumberGenerator & */
    01253         virtual bool IsProbabilistic() const =0;
    01254
    01255         //! whether or not a non-recoverable message part can be signed
    01256         virtual bool AllowNonrecoverablePart() const =0;
    01257
    01258         //! if this function returns true, during verification you must input the signature before the message, otherwise you can input it at anytime */
    01259         virtual bool SignatureUpfront() const {return false;}
    01260
    01261         //! whether you must input the recoverable part before the non-recoverable part during signing
    01262         virtual bool RecoverablePartFirst() const =0;
    01263 };
    01264
    01265 //! interface for accumulating messages to be signed or verified
    01266 /*! Only Update() should be called
    01267         on this class. No other functions inherited from HashTransformation should be called.
    01268 */
    01269 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_MessageAccumulator : public HashTransformation
    01270 {
    01271 public:
    01272         //! should not be called on PK_MessageAccumulator
    01273         unsigned int DigestSize() const
    01274                 {throw NotImplemented("PK_MessageAccumulator: DigestSize() should not be called");}
    01275         //! should not be called on PK_MessageAccumulator
    01276         void TruncatedFinal(byte *digest, size_t digestSize)
    01277                 {throw NotImplemented("PK_MessageAccumulator: TruncatedFinal() should not be called");}
    01278 };
    01279
    01280 //! interface for public-key signers
    01281
    01282 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Signer : public PK_SignatureScheme, public PrivateKeyAlgorithm
    01283 {
    01284 public:
    01285         //! create a new HashTransformation to accumulate the message to be signed
    01286         virtual PK_MessageAccumulator * NewSignatureAccumulator(RandomNumberGenerator &rng) const =0;
    01287
    01288         virtual void InputRecoverableMessage(PK_MessageAccumulator &messageAccumulator, const byte *recoverableMessage, size_t recoverableMessageLength) const =0;
    01289
    01290         //! sign and delete messageAccumulator (even in case of exception thrown)
    01291         /*! \pre size of signature == MaxSignatureLength()
    01292                 \return actual signature length
    01293         */
    01294         virtual size_t Sign(RandomNumberGenerator &rng, PK_MessageAccumulator *messageAccumulator, byte *signature) const;
    01295
    01296         //! sign and restart messageAccumulator
    01297         /*! \pre size of signature == MaxSignatureLength()
    01298                 \return actual signature length
    01299         */
    01300         virtual size_t SignAndRestart(RandomNumberGenerator &rng, PK_MessageAccumulator &messageAccumulator, byte *signature, bool restart=true) const =0;
    01301
    01302         //! sign a message
    01303         /*! \pre size of signature == MaxSignatureLength()
    01304                 \return actual signature length
    01305         */
    01306         virtual size_t SignMessage(RandomNumberGenerator &rng, const byte *message, size_t messageLen, byte *signature) const;
    01307
    01308         //! sign a recoverable message
    01309         /*! \pre size of signature == MaxSignatureLength(recoverableMessageLength)
    01310                 \return actual signature length
    01311         */
    01312         virtual size_t SignMessageWithRecovery(RandomNumberGenerator &rng, const byte *recoverableMessage, size_t recoverableMessageLength,
    01313                 const byte *nonrecoverableMessage, size_t nonrecoverableMessageLength, byte *signature) const;
    01314 };
    01315
    01316 //! interface for public-key signature verifiers
    01317 /*! The Recover* functions throw NotImplemented if the signature scheme does not support
    01318         message recovery.
    01319         The Verify* functions throw InvalidDataFormat if the scheme does support message
    01320         recovery and the signature contains a non-empty recoverable message part. The
    01321         Recovery* functions should be used in that case.
    01322 */
    01323 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE PK_Verifier : public PK_SignatureScheme, public PublicKeyAlgorithm
    01324 {
    01325 public:
    01326         //! create a new HashTransformation to accumulate the message to be verified
    01327         virtual PK_MessageAccumulator * NewVerificationAccumulator() const =0;
    01328
    01329         //! input signature into a message accumulator
    01330         virtual void InputSignature(PK_MessageAccumulator &messageAccumulator, const byte *signature, size_t signatureLength) const =0;
    01331
    01332         //! check whether messageAccumulator contains a valid signature and message, and delete messageAccumulator (even in case of exception thrown)
    01333         virtual bool Verify(PK_MessageAccumulator *messageAccumulator) const;
    01334
    01335         //! check whether messageAccumulator contains a valid signature and message, and restart messageAccumulator
    01336         virtual bool VerifyAndRestart(PK_MessageAccumulator &messageAccumulator) const =0;
    01337
    01338         //! check whether input signature is a valid signature for input message
    01339         virtual bool VerifyMessage(const byte *message, size_t messageLen,
    01340                 const byte *signature, size_t signatureLength) const;
    01341
    01342         //! recover a message from its signature
    01343         /*! \pre size of recoveredMessage == MaxRecoverableLengthFromSignatureLength(signatureLength)
    01344         */
    01345         virtual DecodingResult Recover(byte *recoveredMessage, PK_MessageAccumulator *messageAccumulator) const;
    01346
    01347         //! recover a message from its signature
    01348         /*! \pre size of recoveredMessage == MaxRecoverableLengthFromSignatureLength(signatureLength)
    01349         */
    01350         virtual DecodingResult RecoverAndRestart(byte *recoveredMessage, PK_MessageAccumulator &messageAccumulator) const =0;
    01351
    01352         //! recover a message from its signature
    01353         /*! \pre size of recoveredMessage == MaxRecoverableLengthFromSignatureLength(signatureLength)
    01354         */
    01355         virtual DecodingResult RecoverMessage(byte *recoveredMessage,
    01356                 const byte *nonrecoverableMessage, size_t nonrecoverableMessageLength,
    01357                 const byte *signature, size_t signatureLength) const;
    01358 };
    01359
    01360 //! interface for domains of simple key agreement protocols
    01361
    01362 /*! A key agreement domain is a set of parameters that must be shared
    01363         by two parties in a key agreement protocol, along with the algorithms
    01364         for generating key pairs and deriving agreed values.
    01365 */
    01366 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE SimpleKeyAgreementDomain : public KeyAgreementAlgorithm
    01367 {
    01368 public:
    01369         //! return length of agreed value produced
    01370         virtual unsigned int AgreedValueLength() const =0;
    01371         //! return length of private keys in this domain
    01372         virtual unsigned int PrivateKeyLength() const =0;
    01373         //! return length of public keys in this domain
    01374         virtual unsigned int PublicKeyLength() const =0;
    01375         //! generate private key
    01376         /*! \pre size of privateKey == PrivateKeyLength() */
    01377         virtual void GeneratePrivateKey(RandomNumberGenerator &rng, byte *privateKey) const =0;
    01378         //! generate public key
    01379         /*!     \pre size of publicKey == PublicKeyLength() */
    01380         virtual void GeneratePublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const =0;
    01381         //! generate private/public key pair
    01382         /*! \note equivalent to calling GeneratePrivateKey() and then GeneratePublicKey() */
    01383         virtual void GenerateKeyPair(RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const;
    01384         //! derive agreed value from your private key and couterparty's public key, return false in case of failure
    01385         /*! \note If you have previously validated the public key, use validateOtherPublicKey=false to save time.
    01386                 \pre size of agreedValue == AgreedValueLength()
    01387                 \pre length of privateKey == PrivateKeyLength()
    01388                 \pre length of otherPublicKey == PublicKeyLength()
    01389         */
    01390         virtual bool Agree(byte *agreedValue, const byte *privateKey, const byte *otherPublicKey, bool validateOtherPublicKey=true) const =0;
    01391
    01392 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    01393         bool ValidateDomainParameters(RandomNumberGenerator &rng) const
    01394                 {return GetCryptoParameters().Validate(rng, 2);}
    01395 #endif
    01396 };
    01397
    01398 //! interface for domains of authenticated key agreement protocols
    01399
    01400 /*! In an authenticated key agreement protocol, each party has two
    01401         key pairs. The long-lived key pair is called the static key pair,
    01402         and the short-lived key pair is called the ephemeral key pair.
    01403 */
    01404 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AuthenticatedKeyAgreementDomain : public KeyAgreementAlgorithm
    01405 {
    01406 public:
    01407         //! return length of agreed value produced
    01408         virtual unsigned int AgreedValueLength() const =0;
    01409
    01410         //! return length of static private keys in this domain
    01411         virtual unsigned int StaticPrivateKeyLength() const =0;
    01412         //! return length of static public keys in this domain
    01413         virtual unsigned int StaticPublicKeyLength() const =0;
    01414         //! generate static private key
    01415         /*! \pre size of privateKey == PrivateStaticKeyLength() */
    01416         virtual void GenerateStaticPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const =0;
    01417         //! generate static public key
    01418         /*!     \pre size of publicKey == PublicStaticKeyLength() */
    01419         virtual void GenerateStaticPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const =0;
    01420         //! generate private/public key pair
    01421         /*! \note equivalent to calling GenerateStaticPrivateKey() and then GenerateStaticPublicKey() */
    01422         virtual void GenerateStaticKeyPair(RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const;
    01423
    01424         //! return length of ephemeral private keys in this domain
    01425         virtual unsigned int EphemeralPrivateKeyLength() const =0;
    01426         //! return length of ephemeral public keys in this domain
    01427         virtual unsigned int EphemeralPublicKeyLength() const =0;
    01428         //! generate ephemeral private key
    01429         /*! \pre size of privateKey == PrivateEphemeralKeyLength() */
    01430         virtual void GenerateEphemeralPrivateKey(RandomNumberGenerator &rng, byte *privateKey) const =0;
    01431         //! generate ephemeral public key
    01432         /*!     \pre size of publicKey == PublicEphemeralKeyLength() */
    01433         virtual void GenerateEphemeralPublicKey(RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const =0;
    01434         //! generate private/public key pair
    01435         /*! \note equivalent to calling GenerateEphemeralPrivateKey() and then GenerateEphemeralPublicKey() */
    01436         virtual void GenerateEphemeralKeyPair(RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const;
    01437
    01438         //! derive agreed value from your private keys and couterparty's public keys, return false in case of failure
    01439         /*! \note The ephemeral public key will always be validated.
    01440                       If you have previously validated the static public key, use validateStaticOtherPublicKey=false to save time.
    01441                 \pre size of agreedValue == AgreedValueLength()
    01442                 \pre length of staticPrivateKey == StaticPrivateKeyLength()
    01443                 \pre length of ephemeralPrivateKey == EphemeralPrivateKeyLength()
    01444                 \pre length of staticOtherPublicKey == StaticPublicKeyLength()
    01445                 \pre length of ephemeralOtherPublicKey == EphemeralPublicKeyLength()
    01446         */
    01447         virtual bool Agree(byte *agreedValue,
    01448                 const byte *staticPrivateKey, const byte *ephemeralPrivateKey,
    01449                 const byte *staticOtherPublicKey, const byte *ephemeralOtherPublicKey,
    01450                 bool validateStaticOtherPublicKey=true) const =0;
    01451
    01452 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    01453         bool ValidateDomainParameters(RandomNumberGenerator &rng) const
    01454                 {return GetCryptoParameters().Validate(rng, 2);}
    01455 #endif
    01456 };
    01457
    01458 // interface for password authenticated key agreement protocols, not implemented yet
    01459 #if 0
    01460 //! interface for protocol sessions
    01461 /*! The methods should be called in the following order:
    01462
    01463         InitializeSession(rng, parameters);     // or call initialize method in derived class
    01464         while (true)
    01465         {
    01466                 if (OutgoingMessageAvailable())
    01467                 {
    01468                         length = GetOutgoingMessageLength();
    01469                         GetOutgoingMessage(message);
    01470                         ; // send outgoing message
    01471                 }
    01472
    01473                 if (LastMessageProcessed())
    01474                         break;
    01475
    01476                 ; // receive incoming message
    01477                 ProcessIncomingMessage(message);
    01478         }
    01479         ; // call methods in derived class to obtain result of protocol session
    01480 */
    01481 class ProtocolSession
    01482 {
    01483 public:
    01484         //! exception thrown when an invalid protocol message is processed
    01485         class ProtocolError : public Exception
    01486         {
    01487         public:
    01488                 ProtocolError(ErrorType errorType, const std::string &s) : Exception(errorType, s) {}
    01489         };
    01490
    01491         //! exception thrown when a function is called unexpectedly
    01492         /*! for example calling ProcessIncomingMessage() when ProcessedLastMessage() == true */
    01493         class UnexpectedMethodCall : public Exception
    01494         {
    01495         public:
    01496                 UnexpectedMethodCall(const std::string &s) : Exception(OTHER_ERROR, s) {}
    01497         };
    01498
    01499         ProtocolSession() : m_rng(NULL), m_throwOnProtocolError(true), m_validState(false) {}
    01500         virtual ~ProtocolSession() {}
    01501
    01502         virtual void InitializeSession(RandomNumberGenerator &rng, const NameValuePairs &parameters) =0;
    01503
    01504         bool GetThrowOnProtocolError() const {return m_throwOnProtocolError;}
    01505         void SetThrowOnProtocolError(bool throwOnProtocolError) {m_throwOnProtocolError = throwOnProtocolError;}
    01506
    01507         bool HasValidState() const {return m_validState;}
    01508
    01509         virtual bool OutgoingMessageAvailable() const =0;
    01510         virtual unsigned int GetOutgoingMessageLength() const =0;
    01511         virtual void GetOutgoingMessage(byte *message) =0;
    01512
    01513         virtual bool LastMessageProcessed() const =0;
    01514         virtual void ProcessIncomingMessage(const byte *message, unsigned int messageLength) =0;
    01515
    01516 protected:
    01517         void HandleProtocolError(Exception::ErrorType errorType, const std::string &s) const;
    01518         void CheckAndHandleInvalidState() const;
    01519         void SetValidState(bool valid) {m_validState = valid;}
    01520
    01521         RandomNumberGenerator *m_rng;
    01522
    01523 private:
    01524         bool m_throwOnProtocolError, m_validState;
    01525 };
    01526
    01527 class KeyAgreementSession : public ProtocolSession
    01528 {
    01529 public:
    01530         virtual unsigned int GetAgreedValueLength() const =0;
    01531         virtual void GetAgreedValue(byte *agreedValue) const =0;
    01532 };
    01533
    01534 class PasswordAuthenticatedKeyAgreementSession : public KeyAgreementSession
    01535 {
    01536 public:
    01537         void InitializePasswordAuthenticatedKeyAgreementSession(RandomNumberGenerator &rng,
    01538                 const byte *myId, unsigned int myIdLength,
    01539                 const byte *counterPartyId, unsigned int counterPartyIdLength,
    01540                 const byte *passwordOrVerifier, unsigned int passwordOrVerifierLength);
    01541 };
    01542
    01543 class PasswordAuthenticatedKeyAgreementDomain : public KeyAgreementAlgorithm
    01544 {
    01545 public:
    01546         //! return whether the domain parameters stored in this object are valid
    01547         virtual bool ValidateDomainParameters(RandomNumberGenerator &rng) const
    01548                 {return GetCryptoParameters().Validate(rng, 2);}
    01549
    01550         virtual unsigned int GetPasswordVerifierLength(const byte *password, unsigned int passwordLength) const =0;
    01551         virtual void GeneratePasswordVerifier(RandomNumberGenerator &rng, const byte *userId, unsigned int userIdLength, const byte *password, unsigned int passwordLength, byte *verifier) const =0;
    01552
    01553         enum RoleFlags {CLIENT=1, SERVER=2, INITIATOR=4, RESPONDER=8};
    01554
    01555         virtual bool IsValidRole(unsigned int role) =0;
    01556         virtual PasswordAuthenticatedKeyAgreementSession * CreateProtocolSession(unsigned int role) const =0;
    01557 };
    01558 #endif
    01559
    01560 //! BER Decode Exception Class, may be thrown during an ASN1 BER decode operation
    01561 class CRYPTOPP_DLL BERDecodeErr : public InvalidArgument
    01562 {
    01563 public:
    01564         BERDecodeErr() : InvalidArgument("BER decode error") {}
    01565         BERDecodeErr(const std::string &s) : InvalidArgument(s) {}
    01566 };
    01567
    01568 //! interface for encoding and decoding ASN1 objects
    01569 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE ASN1Object
    01570 {
    01571 public:
    01572         virtual ~ASN1Object() {}
    01573         //! decode this object from a BufferedTransformation, using BER (Basic Encoding Rules)
    01574         virtual void BERDecode(BufferedTransformation &bt) =0;
    01575         //! encode this object into a BufferedTransformation, using DER (Distinguished Encoding Rules)
    01576         virtual void DEREncode(BufferedTransformation &bt) const =0;
    01577         //! encode this object into a BufferedTransformation, using BER
    01578         /*! this may be useful if DEREncode() would be too inefficient */
    01579         virtual void BEREncode(BufferedTransformation &bt) const {DEREncode(bt);}
    01580 };
    01581
    01582 #ifdef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY
    01583 typedef PK_SignatureScheme PK_SignatureSystem;
    01584 typedef SimpleKeyAgreementDomain PK_SimpleKeyAgreementDomain;
    01585 typedef AuthenticatedKeyAgreementDomain PK_AuthenticatedKeyAgreementDomain;
    01586 #endif
    01587
    01588 NAMESPACE_END
    01589
    01590 #endif