00001 // seckey.h - written and placed in the public domain by Wei Dai 00002 00003 //! \file 00004 //! \brief Classes and functions for implementing secret key algorithms. 00005 00006 #ifndef CRYPTOPP_SECKEY_H 00007 #define CRYPTOPP_SECKEY_H 00008 00009 #include "config.h" 00010 00011 #if CRYPTOPP_MSC_VERSION 00012 # pragma warning(push) 00013 # pragma warning(disable: 4189) 00014 #endif 00015 00016 #include "cryptlib.h" 00017 #include "misc.h" 00018 #include "simple.h" 00019 00020 NAMESPACE_BEGIN(CryptoPP) 00021 00022 //! \brief Inverts the cipher's direction 00023 //! \param dir the cipher's direction 00024 //! \returns DECRYPTION if dir is ENCRYPTION, DECRYPTION otherwise 00025 inline CipherDir ReverseCipherDir(CipherDir dir) 00026 { 00027 return (dir == ENCRYPTION) ? DECRYPTION : ENCRYPTION; 00028 } 00029 00030 //! \class FixedBlockSize 00031 //! \brief Inherited by block ciphers with fixed block size 00032 //! \tparam N the blocksize of the cipher 00033 template <unsigned int N> 00034 class FixedBlockSize 00035 { 00036 public: 00037 //! \brief The block size of the cipher provided as a constant. 00038 CRYPTOPP_CONSTANT(BLOCKSIZE = N) 00039 }; 00040 00041 // ************** rounds *************** 00042 00043 //! \class FixedRounds 00044 //! \brief Inherited by ciphers with fixed number of rounds 00045 //! \tparam R the number of rounds used by the cipher 00046 template <unsigned int R> 00047 class FixedRounds 00048 { 00049 public: 00050 //! \brief The number of rounds for the cipher provided as a constant. 00051 CRYPTOPP_CONSTANT(ROUNDS = R) 00052 }; 00053 00054 //! \class VariableRounds 00055 //! \brief Inherited by ciphers with variable number of rounds 00056 //! \tparam D Default number of rounds 00057 //! \tparam N Minimum number of rounds 00058 //! \tparam D Maximum number of rounds 00059 template <unsigned int D, unsigned int N=1, unsigned int M=INT_MAX> // use INT_MAX here because enums are treated as signed ints 00060 class VariableRounds 00061 { 00062 public: 00063 //! \brief The default number of rounds for the cipher provided as a constant. 00064 CRYPTOPP_CONSTANT(DEFAULT_ROUNDS = D) 00065 //! \brief The minimum number of rounds for the cipher provided as a constant. 00066 CRYPTOPP_CONSTANT(MIN_ROUNDS = N) 00067 //! \brief The maximum number of rounds for the cipher provided as a constant. 00068 CRYPTOPP_CONSTANT(MAX_ROUNDS = M) 00069 //! \brief The default number of rounds for the cipher based on key length 00070 //! provided by a static function. 00071 //! \param keylength the size of the key, in bytes 00072 //! \details keylength is unused in the default implementation. 00073 static unsigned int StaticGetDefaultRounds(size_t keylength) 00074 {CRYPTOPP_UNUSED(keylength); return DEFAULT_ROUNDS;} 00075 00076 protected: 00077 //! \brief Validates the number of rounds for a cipher. 00078 //! \param rounds the canddiate number of rounds 00079 //! \param alg an Algorithm object used if the number of rounds are invalid 00080 //! \throws InvalidRounds if the number of rounds are invalid 00081 inline void ThrowIfInvalidRounds(int rounds, const Algorithm *alg) 00082 { 00083 #if (M==INT_MAX) // Coverity and result_independent_of_operands 00084 if (rounds < MIN_ROUNDS) 00085 throw InvalidRounds(alg ? alg->AlgorithmName() : "VariableRounds", rounds); 00086 #else 00087 if (rounds < MIN_ROUNDS || rounds > MAX_ROUNDS) 00088 throw InvalidRounds(alg ? alg->AlgorithmName() : "VariableRounds", rounds); 00089 #endif 00090 } 00091 00092 //! \brief Validates the number of rounds for a cipher 00093 //! \param param the canddiate number of rounds 00094 //! \param alg an Algorithm object used if the number of rounds are invalid 00095 //! \returns the number of rounds for the cipher 00096 //! \throws InvalidRounds if the number of rounds are invalid 00097 inline unsigned int GetRoundsAndThrowIfInvalid(const NameValuePairs ¶m, const Algorithm *alg) 00098 { 00099 int rounds = param.GetIntValueWithDefault("Rounds", DEFAULT_ROUNDS); 00100 ThrowIfInvalidRounds(rounds, alg); 00101 return (unsigned int)rounds; 00102 } 00103 }; 00104 00105 // ************** key length *************** 00106 00107 //! \class FixedKeyLength 00108 //! \brief Inherited by keyed algorithms with fixed key length 00109 //! \tparam N Default key length, in bytes 00110 //! \tparam IV_REQ The IV requirements. See IV_Requirement in cryptlib.h for allowed values 00111 //! \tparam IV_L Default IV length, in bytes 00112 template <unsigned int N, unsigned int IV_REQ = SimpleKeyingInterface::NOT_RESYNCHRONIZABLE, unsigned int IV_L = 0> 00113 class FixedKeyLength 00114 { 00115 public: 00116 //! \brief The default key length used by the cipher provided as a constant 00117 //! \details KEYLENGTH is provided in bytes, not bits 00118 CRYPTOPP_CONSTANT(KEYLENGTH=N) 00119 //! \brief The minimum key length used by the cipher provided as a constant 00120 //! \details MIN_KEYLENGTH is provided in bytes, not bits 00121 CRYPTOPP_CONSTANT(MIN_KEYLENGTH=N) 00122 //! \brief The maximum key length used by the cipher provided as a constant 00123 //! \details MAX_KEYLENGTH is provided in bytes, not bits 00124 CRYPTOPP_CONSTANT(MAX_KEYLENGTH=N) 00125 //! \brief The default key length used by the cipher provided as a constant 00126 //! \details DEFAULT_KEYLENGTH is provided in bytes, not bits 00127 CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=N) 00128 //! \brief The default IV requirements for the cipher provided as a constant 00129 //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement 00130 //! in cryptlib.h for allowed values. 00131 CRYPTOPP_CONSTANT(IV_REQUIREMENT = IV_REQ) 00132 //! \brief The default IV length used by the cipher provided as a constant 00133 //! \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. 00134 CRYPTOPP_CONSTANT(IV_LENGTH = IV_L) 00135 //! \brief The default key length for the cipher provided by a static function. 00136 //! \param keylength the size of the key, in bytes 00137 //! \details The default implementation returns KEYLENGTH. keylength is unused 00138 //! in the default implementation. 00139 static size_t CRYPTOPP_API StaticGetValidKeyLength(size_t keylength) 00140 {CRYPTOPP_UNUSED(keylength); return KEYLENGTH;} 00141 }; 00142 00143 //! \class VariableKeyLength 00144 //! \brief Inherited by keyed algorithms with variable key length 00145 //! \tparam D Default key length, in bytes 00146 //! \tparam N Minimum key length, in bytes 00147 //! \tparam M Maximum key length, in bytes 00148 //! \tparam M Default key length multiple, in bytes. The default multiple is 1. 00149 //! \tparam IV_REQ The IV requirements. See IV_Requirement in cryptlib.h for allowed values 00150 //! \tparam IV_L Default IV length, in bytes. The default length is 0. 00151 template <unsigned int D, unsigned int N, unsigned int M, unsigned int Q = 1, unsigned int IV_REQ = SimpleKeyingInterface::NOT_RESYNCHRONIZABLE, unsigned int IV_L = 0> 00152 class VariableKeyLength 00153 { 00154 // Make these private to avoid Doxygen documenting them in all derived classes 00155 CRYPTOPP_COMPILE_ASSERT(Q > 0); 00156 CRYPTOPP_COMPILE_ASSERT(N % Q == 0); 00157 CRYPTOPP_COMPILE_ASSERT(M % Q == 0); 00158 CRYPTOPP_COMPILE_ASSERT(N < M); 00159 CRYPTOPP_COMPILE_ASSERT(D >= N); 00160 CRYPTOPP_COMPILE_ASSERT(M >= D); 00161 00162 public: 00163 //! \brief The minimum key length used by the cipher provided as a constant 00164 //! \details MIN_KEYLENGTH is provided in bytes, not bits 00165 CRYPTOPP_CONSTANT(MIN_KEYLENGTH=N) 00166 //! \brief The maximum key length used by the cipher provided as a constant 00167 //! \details MAX_KEYLENGTH is provided in bytes, not bits 00168 CRYPTOPP_CONSTANT(MAX_KEYLENGTH=M) 00169 //! \brief The default key length used by the cipher provided as a constant 00170 //! \details DEFAULT_KEYLENGTH is provided in bytes, not bits 00171 CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=D) 00172 //! \brief The key length multiple used by the cipher provided as a constant 00173 //! \details MAX_KEYLENGTH is provided in bytes, not bits 00174 CRYPTOPP_CONSTANT(KEYLENGTH_MULTIPLE=Q) 00175 //! \brief The default IV requirements for the cipher provided as a constant 00176 //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement 00177 //! in cryptlib.h for allowed values. 00178 CRYPTOPP_CONSTANT(IV_REQUIREMENT=IV_REQ) 00179 //! \brief The default initialization vector length for the cipher provided as a constant 00180 //! \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. 00181 CRYPTOPP_CONSTANT(IV_LENGTH=IV_L) 00182 //! \brief Provides a valid key length for the cipher provided by a static function. 00183 //! \param keylength the size of the key, in bytes 00184 //! \details If keylength is less than MIN_KEYLENGTH, then the function returns 00185 //! MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, then the function 00186 //! returns MAX_KEYLENGTH. If keylength is a multiple of KEYLENGTH_MULTIPLE, 00187 //! then keylength is returned. Otherwise, the function returns keylength rounded 00188 //! \a down to the next smaller multiple of KEYLENGTH_MULTIPLE. 00189 //! \details keylength is provided in bytes, not bits. 00190 static size_t CRYPTOPP_API StaticGetValidKeyLength(size_t keylength) 00191 { 00192 #if MIN_KEYLENGTH > 0 00193 if (keylength < (size_t)MIN_KEYLENGTH) 00194 return MIN_KEYLENGTH; 00195 else 00196 #endif 00197 if (keylength > (size_t)MAX_KEYLENGTH) 00198 return (size_t)MAX_KEYLENGTH; 00199 else 00200 { 00201 keylength += KEYLENGTH_MULTIPLE-1; 00202 return keylength - keylength%KEYLENGTH_MULTIPLE; 00203 } 00204 } 00205 }; 00206 00207 //! \class SameKeyLengthAs 00208 //! \brief Provides key lengths based on another class's key length 00209 //! \tparam T another FixedKeyLength or VariableKeyLength class 00210 //! \tparam IV_REQ The IV requirements. See IV_Requirement in cryptlib.h for allowed values 00211 //! \tparam IV_L Default IV length, in bytes 00212 template <class T, unsigned int IV_REQ = SimpleKeyingInterface::NOT_RESYNCHRONIZABLE, unsigned int IV_L = 0> 00213 class SameKeyLengthAs 00214 { 00215 public: 00216 //! \brief The minimum key length used by the cipher provided as a constant 00217 //! \details MIN_KEYLENGTH is provided in bytes, not bits 00218 CRYPTOPP_CONSTANT(MIN_KEYLENGTH=T::MIN_KEYLENGTH) 00219 //! \brief The maximum key length used by the cipher provided as a constant 00220 //! \details MIN_KEYLENGTH is provided in bytes, not bits 00221 CRYPTOPP_CONSTANT(MAX_KEYLENGTH=T::MAX_KEYLENGTH) 00222 //! \brief The default key length used by the cipher provided as a constant 00223 //! \details MIN_KEYLENGTH is provided in bytes, not bits 00224 CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=T::DEFAULT_KEYLENGTH) 00225 //! \brief The default IV requirements for the cipher provided as a constant 00226 //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement 00227 //! in cryptlib.h for allowed values. 00228 CRYPTOPP_CONSTANT(IV_REQUIREMENT=IV_REQ) 00229 //! \brief The default initialization vector length for the cipher provided as a constant 00230 //! \details IV_LENGTH is provided in bytes, not bits. The default implementation uses 0. 00231 CRYPTOPP_CONSTANT(IV_LENGTH=IV_L) 00232 //! \brief Provides a valid key length for the cipher provided by a static function. 00233 //! \param keylength the size of the key, in bytes 00234 //! \details If keylength is less than MIN_KEYLENGTH, then the function returns 00235 //! MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, then the function 00236 //! returns MAX_KEYLENGTH. If keylength is a multiple of KEYLENGTH_MULTIPLE, 00237 //! then keylength is returned. Otherwise, the function returns keylength rounded 00238 //! \a down to the next smaller multiple of KEYLENGTH_MULTIPLE. 00239 //! \details keylength is provided in bytes, not bits. 00240 static size_t CRYPTOPP_API StaticGetValidKeyLength(size_t keylength) 00241 {return T::StaticGetValidKeyLength(keylength);} 00242 }; 00243 00244 // ************** implementation helper for SimpleKeyed *************** 00245 00246 //! \class SimpleKeyingInterfaceImpl 00247 //! \brief Provides class member functions to access SimpleKeyingInterface constants 00248 //! \tparam BASE a SimpleKeyingInterface derived class 00249 //! \tparam INFO a SimpleKeyingInterface derived class 00250 template <class BASE, class INFO = BASE> 00251 class CRYPTOPP_NO_VTABLE SimpleKeyingInterfaceImpl : public BASE 00252 { 00253 public: 00254 //! \brief The minimum key length used by the cipher 00255 size_t MinKeyLength() const 00256 {return INFO::MIN_KEYLENGTH;} 00257 00258 //! \brief The maximum key length used by the cipher 00259 size_t MaxKeyLength() const 00260 {return (size_t)INFO::MAX_KEYLENGTH;} 00261 00262 //! \brief The default key length used by the cipher 00263 size_t DefaultKeyLength() const 00264 {return INFO::DEFAULT_KEYLENGTH;} 00265 00266 //! \brief Provides a valid key length for the cipher 00267 //! \param keylength the size of the key, in bytes 00268 //! \details keylength is provided in bytes, not bits. If keylength is less than MIN_KEYLENGTH, 00269 //! then the function returns MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, 00270 //! then the function returns MAX_KEYLENGTH. if If keylength is a multiple of KEYLENGTH_MULTIPLE, 00271 //! then keylength is returned. Otherwise, the function returns a \a lower multiple of 00272 //! KEYLENGTH_MULTIPLE. 00273 size_t GetValidKeyLength(size_t keylength) const {return INFO::StaticGetValidKeyLength(keylength);} 00274 00275 //! \brief The default IV requirements for the cipher 00276 //! \details The default value is NOT_RESYNCHRONIZABLE. See IV_Requirement 00277 //! in cryptlib.h for allowed values. 00278 SimpleKeyingInterface::IV_Requirement IVRequirement() const 00279 {return (SimpleKeyingInterface::IV_Requirement)INFO::IV_REQUIREMENT;} 00280 00281 //! \brief The default initialization vector length for the cipher 00282 //! \details IVSize is provided in bytes, not bits. The default implementation uses IV_LENGTH, which is 0. 00283 unsigned int IVSize() const 00284 {return INFO::IV_LENGTH;} 00285 }; 00286 00287 //! \class BlockCipherImpl 00288 //! \brief Provides class member functions to access BlockCipher constants 00289 //! \tparam INFO a SimpleKeyingInterface derived class 00290 //! \tparam BASE a SimpleKeyingInterface derived class 00291 template <class INFO, class BASE = BlockCipher> 00292 class CRYPTOPP_NO_VTABLE BlockCipherImpl : public AlgorithmImpl<SimpleKeyingInterfaceImpl<TwoBases<BASE, INFO> > > 00293 { 00294 public: 00295 //! Provides the block size of the cipher 00296 //! \returns the block size of the cipher, in bytes 00297 unsigned int BlockSize() const {return this->BLOCKSIZE;} 00298 }; 00299 00300 //! \class BlockCipherFinal 00301 //! \brief Provides class member functions to key a block cipher 00302 //! \tparam DIR a CipherDir 00303 //! \tparam BASE a BlockCipherImpl derived class 00304 template <CipherDir DIR, class BASE> 00305 class BlockCipherFinal : public ClonableImpl<BlockCipherFinal<DIR, BASE>, BASE> 00306 { 00307 public: 00308 //! \brief Construct a default BlockCipherFinal 00309 //! \details The cipher is not keyed. 00310 BlockCipherFinal() {} 00311 00312 //! \brief Construct a BlockCipherFinal 00313 //! \param key a byte array used to key the cipher 00314 //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls 00315 //! SimpleKeyingInterface::SetKey. 00316 BlockCipherFinal(const byte *key) 00317 {this->SetKey(key, this->DEFAULT_KEYLENGTH);} 00318 00319 //! \brief Construct a BlockCipherFinal 00320 //! \param key a byte array used to key the cipher 00321 //! \param length the length of the byte array 00322 //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls 00323 //! SimpleKeyingInterface::SetKey. 00324 BlockCipherFinal(const byte *key, size_t length) 00325 {this->SetKey(key, length);} 00326 00327 //! \brief Construct a BlockCipherFinal 00328 //! \param key a byte array used to key the cipher 00329 //! \param length the length of the byte array 00330 //! \param rounds the number of rounds 00331 //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls 00332 //! SimpleKeyingInterface::SetKeyWithRounds. 00333 BlockCipherFinal(const byte *key, size_t length, unsigned int rounds) 00334 {this->SetKeyWithRounds(key, length, rounds);} 00335 00336 //! \brief Provides the direction of the cipher 00337 //! \returns true if DIR is ENCRYPTION, false otherwise 00338 //! \sa IsForwardTransformation(), IsPermutation(), GetCipherDirection() 00339 bool IsForwardTransformation() const {return DIR == ENCRYPTION;} 00340 }; 00341 00342 //! \class MessageAuthenticationCodeImpl 00343 //! \brief Provides class member functions to access MessageAuthenticationCode constants 00344 //! \tparam INFO a SimpleKeyingInterface derived class 00345 //! \tparam BASE a SimpleKeyingInterface derived class 00346 template <class BASE, class INFO = BASE> 00347 class MessageAuthenticationCodeImpl : public AlgorithmImpl<SimpleKeyingInterfaceImpl<BASE, INFO>, INFO> 00348 { 00349 }; 00350 00351 //! \class MessageAuthenticationCodeFinal 00352 //! \brief Provides class member functions to key a message authentication code 00353 //! \tparam DIR a CipherDir 00354 //! \tparam BASE a BlockCipherImpl derived class 00355 template <class BASE> 00356 class MessageAuthenticationCodeFinal : public ClonableImpl<MessageAuthenticationCodeFinal<BASE>, MessageAuthenticationCodeImpl<BASE> > 00357 { 00358 public: 00359 //! \brief Construct a default MessageAuthenticationCodeFinal 00360 //! \details The message authentication code is not keyed. 00361 MessageAuthenticationCodeFinal() {} 00362 //! \brief Construct a BlockCipherFinal 00363 //! \param key a byte array used to key the cipher 00364 //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls 00365 //! SimpleKeyingInterface::SetKey. 00366 MessageAuthenticationCodeFinal(const byte *key) 00367 {this->SetKey(key, this->DEFAULT_KEYLENGTH);} 00368 //! \brief Construct a BlockCipherFinal 00369 //! \param key a byte array used to key the cipher 00370 //! \param length the length of the byte array 00371 //! \details key must be at least DEFAULT_KEYLENGTH in length. Internally, the function calls 00372 //! SimpleKeyingInterface::SetKey. 00373 MessageAuthenticationCodeFinal(const byte *key, size_t length) 00374 {this->SetKey(key, length);} 00375 }; 00376 00377 // ************** documentation *************** 00378 00379 //! \class BlockCipherDocumentation 00380 //! \brief Provides Encryption and Decryption typedefs used by derived classes to 00381 //! implement a block cipher 00382 //! \details These objects usually should not be used directly. See CipherModeDocumentation 00383 //! instead. Each class derived from this one defines two types, Encryption and Decryption, 00384 //! both of which implement the BlockCipher interface. 00385 struct BlockCipherDocumentation 00386 { 00387 //! implements the BlockCipher interface 00388 typedef BlockCipher Encryption; 00389 //! implements the BlockCipher interface 00390 typedef BlockCipher Decryption; 00391 }; 00392 00393 //! \class SymmetricCipherDocumentation 00394 //! \brief Provides Encryption and Decryption typedefs used by derived classes to 00395 //! implement a symmetric cipher 00396 //! \details Each class derived from this one defines two types, Encryption and Decryption, 00397 //! both of which implement the SymmetricCipher interface. Two types of classes derive 00398 //! from this class: stream ciphers and block cipher modes. Stream ciphers can be used 00399 //! alone, cipher mode classes need to be used with a block cipher. See CipherModeDocumentation 00400 //! for more for information about using cipher modes and block ciphers. 00401 struct SymmetricCipherDocumentation 00402 { 00403 //! implements the SymmetricCipher interface 00404 typedef SymmetricCipher Encryption; 00405 //! implements the SymmetricCipher interface 00406 typedef SymmetricCipher Decryption; 00407 }; 00408 00409 //! \class AuthenticatedSymmetricCipherDocumentation 00410 //! \brief Provides Encryption and Decryption typedefs used by derived classes to 00411 //! implement an authenticated encryption cipher 00412 //! \details Each class derived from this one defines two types, Encryption and Decryption, 00413 //! both of which implement the AuthenticatedSymmetricCipher interface. 00414 struct AuthenticatedSymmetricCipherDocumentation 00415 { 00416 //! implements the AuthenticatedSymmetricCipher interface 00417 typedef AuthenticatedSymmetricCipher Encryption; 00418 //! implements the AuthenticatedSymmetricCipher interface 00419 typedef AuthenticatedSymmetricCipher Decryption; 00420 }; 00421 00422 NAMESPACE_END 00423 00424 #if CRYPTOPP_MSC_VERSION 00425 # pragma warning(pop) 00426 #endif 00427 00428 #endif