Crypto++  5.6.3
Free C++ class library of cryptographic schemes
pwdbased.h
Go to the documentation of this file.
1 // pwdbased.h - written and placed in the public domain by Wei Dai
2 
3 //! \file pwdbased.h
4 //! \brief Password based key derivation functions
5 
6 #ifndef CRYPTOPP_PWDBASED_H
7 #define CRYPTOPP_PWDBASED_H
8 
9 #include "cryptlib.h"
10 #include "hrtimer.h"
11 #include "integer.h"
12 #include "hmac.h"
13 
14 NAMESPACE_BEGIN(CryptoPP)
15 
16 //! \brief Abstract base class for password based key derivation function
18 {
19 public:
20 #ifndef CRYPTOPP_MAINTAIN_BACKWARDS_COMPATIBILITY_562
21  virtual ~PasswordBasedKeyDerivationFunction() {}
22 #endif
23 
24  //! \brief Provides the maximum derived key length
25  //! \returns maximum derived key length, in bytes
26  virtual size_t MaxDerivedKeyLength() const =0;
27 
28  //! \brief Determines if the derivation function uses the purpose byte
29  //! \returns true if the derivation function uses the purpose byte, false otherwise
30  virtual bool UsesPurposeByte() const =0;
31 
32  //! \brief Derive key from the password
33  //! \param derived the byte buffer to receive the derived password
34  //! \param derivedLen the size of the byte buffer to receive the derived password
35  //! \param purpose an octet indicating the purpose of the derivation
36  //! \param password the byte buffer with the password
37  //! \param passwordLen the size of the password, in bytes
38  //! \param salt the byte buffer with the salt
39  //! \param saltLen the size of the salt, in bytes
40  //! \param iterations the number of iterations to attempt
41  //! \param timeInSeconds the length of time the derivation function should execute
42  //! \returns iteration count achieved
43  //! \details DeriveKey returns the actual iteration count achieved. If <tt>timeInSeconds == 0</tt>, then the complete number
44  //! of iterations will be obtained. If <tt>timeInSeconds != 0</tt>, then DeriveKey will iterate until time elapsed, as
45  //! measured by ThreadUserTimer.
46  virtual unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds=0) const =0;
47 };
48 
49 //! \brief PBKDF1 from PKCS #5
50 //! \tparam T a HashTransformation class
51 template <class T>
53 {
54 public:
55  size_t MaxDerivedKeyLength() const {return T::DIGESTSIZE;}
56  bool UsesPurposeByte() const {return false;}
57  // PKCS #5 says PBKDF1 should only take 8-byte salts. This implementation allows salts of any length.
58  unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds=0) const;
59 };
60 
61 //! \brief PBKDF2 from PKCS #5
62 //! \tparam T a HashTransformation class
63 template <class T>
65 {
66 public:
67  size_t MaxDerivedKeyLength() const {return 0xffffffffU;} // should multiply by T::DIGESTSIZE, but gets overflow that way
68  bool UsesPurposeByte() const {return false;}
69  unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds=0) const;
70 };
71 
72 /*
73 class PBKDF2Params
74 {
75 public:
76  SecByteBlock m_salt;
77  unsigned int m_interationCount;
78  ASNOptional<ASNUnsignedWrapper<word32> > m_keyLength;
79 };
80 */
81 
82 template <class T>
83 unsigned int PKCS5_PBKDF1<T>::DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds) const
84 {
85  CRYPTOPP_UNUSED(purpose);
86  assert(derivedLen <= MaxDerivedKeyLength());
87  assert(iterations > 0 || timeInSeconds > 0);
88 
89  if (!iterations)
90  iterations = 1;
91 
92  T hash;
93  hash.Update(password, passwordLen);
94  hash.Update(salt, saltLen);
95 
96  SecByteBlock buffer(hash.DigestSize());
97  hash.Final(buffer);
98 
99  unsigned int i;
100  ThreadUserTimer timer;
101 
102  if (timeInSeconds)
103  timer.StartTimer();
104 
105  for (i=1; i<iterations || (timeInSeconds && (i%128!=0 || timer.ElapsedTimeAsDouble() < timeInSeconds)); i++)
106  hash.CalculateDigest(buffer, buffer, buffer.size());
107 
108  memcpy(derived, buffer, derivedLen);
109  return i;
110 }
111 
112 template <class T>
113 unsigned int PKCS5_PBKDF2_HMAC<T>::DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds) const
114 {
115  CRYPTOPP_UNUSED(purpose);
116  assert(derivedLen <= MaxDerivedKeyLength());
117  assert(iterations > 0 || timeInSeconds > 0);
118 
119  if (!iterations)
120  iterations = 1;
121 
122  HMAC<T> hmac(password, passwordLen);
123  SecByteBlock buffer(hmac.DigestSize());
124  ThreadUserTimer timer;
125 
126  unsigned int i=1;
127  while (derivedLen > 0)
128  {
129  hmac.Update(salt, saltLen);
130  unsigned int j;
131  for (j=0; j<4; j++)
132  {
133  byte b = byte(i >> ((3-j)*8));
134  hmac.Update(&b, 1);
135  }
136  hmac.Final(buffer);
137 
138 #if CRYPTOPP_MSC_VERSION
139  const size_t segmentLen = STDMIN(derivedLen, buffer.size());
140  memcpy_s(derived, segmentLen, buffer, segmentLen);
141 #else
142  const size_t segmentLen = STDMIN(derivedLen, buffer.size());
143  memcpy(derived, buffer, segmentLen);
144 #endif
145 
146  if (timeInSeconds)
147  {
148  timeInSeconds = timeInSeconds / ((derivedLen + buffer.size() - 1) / buffer.size());
149  timer.StartTimer();
150  }
151 
152  for (j=1; j<iterations || (timeInSeconds && (j%128!=0 || timer.ElapsedTimeAsDouble() < timeInSeconds)); j++)
153  {
154  hmac.CalculateDigest(buffer, buffer, buffer.size());
155  xorbuf(derived, buffer, segmentLen);
156  }
157 
158  if (timeInSeconds)
159  {
160  iterations = j;
161  timeInSeconds = 0;
162  }
163 
164  derived += segmentLen;
165  derivedLen -= segmentLen;
166  i++;
167  }
168 
169  return iterations;
170 }
171 
172 //! \brief PBKDF from PKCS #12, appendix B
173 //! \tparam T a HashTransformation class
174 template <class T>
176 {
177 public:
178  size_t MaxDerivedKeyLength() const {return size_t(0)-1;}
179  bool UsesPurposeByte() const {return true;}
180  unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds) const;
181 };
182 
183 template <class T>
184 unsigned int PKCS12_PBKDF<T>::DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds) const
185 {
186  assert(derivedLen <= MaxDerivedKeyLength());
187  assert(iterations > 0 || timeInSeconds > 0);
188 
189  if (!iterations)
190  iterations = 1;
191 
192  const size_t v = T::BLOCKSIZE; // v is in bytes rather than bits as in PKCS #12
193  const size_t DLen = v, SLen = RoundUpToMultipleOf(saltLen, v);
194  const size_t PLen = RoundUpToMultipleOf(passwordLen, v), ILen = SLen + PLen;
195  SecByteBlock buffer(DLen + SLen + PLen);
196  byte *D = buffer, *S = buffer+DLen, *P = buffer+DLen+SLen, *I = S;
197 
198  memset(D, purpose, DLen);
199  size_t i;
200  for (i=0; i<SLen; i++)
201  S[i] = salt[i % saltLen];
202  for (i=0; i<PLen; i++)
203  P[i] = password[i % passwordLen];
204 
205 
206  T hash;
207  SecByteBlock Ai(T::DIGESTSIZE), B(v);
208  ThreadUserTimer timer;
209 
210  while (derivedLen > 0)
211  {
212  hash.CalculateDigest(Ai, buffer, buffer.size());
213 
214  if (timeInSeconds)
215  {
216  timeInSeconds = timeInSeconds / ((derivedLen + Ai.size() - 1) / Ai.size());
217  timer.StartTimer();
218  }
219 
220  for (i=1; i<iterations || (timeInSeconds && (i%128!=0 || timer.ElapsedTimeAsDouble() < timeInSeconds)); i++)
221  hash.CalculateDigest(Ai, Ai, Ai.size());
222 
223  if (timeInSeconds)
224  {
225  iterations = (unsigned int)i;
226  timeInSeconds = 0;
227  }
228 
229  for (i=0; i<B.size(); i++)
230  B[i] = Ai[i % Ai.size()];
231 
232  Integer B1(B, B.size());
233  ++B1;
234  for (i=0; i<ILen; i+=v)
235  (Integer(I+i, v) + B1).Encode(I+i, v);
236 
237 #if CRYPTOPP_MSC_VERSION
238  const size_t segmentLen = STDMIN(derivedLen, Ai.size());
239  memcpy_s(derived, segmentLen, Ai, segmentLen);
240 #else
241  const size_t segmentLen = STDMIN(derivedLen, Ai.size());
242  std::memcpy(derived, Ai, segmentLen);
243 #endif
244 
245  derived += segmentLen;
246  derivedLen -= segmentLen;
247  }
248 
249  return iterations;
250 }
251 
252 NAMESPACE_END
253 
254 #endif
unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds=0) const
Derive key from the password.
Definition: pwdbased.h:83
unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds) const
Derive key from the password.
Definition: pwdbased.h:184
Abstract base class for password based key derivation function.
Definition: pwdbased.h:17
Abstract base classes that provide a uniform interface to this library.
void memcpy_s(void *dest, size_t sizeInBytes, const void *src, size_t count)
Bounds checking replacement for memcpy()
Definition: misc.h:354
size_type size() const
Provides the count of elements in the SecBlock.
Definition: secblock.h:521
SecBlock typedef.
Definition: secblock.h:728
size_t MaxDerivedKeyLength() const
Provides the maximum derived key length.
Definition: pwdbased.h:67
PBKDF2 from PKCS #5.
Definition: pwdbased.h:64
bool UsesPurposeByte() const
Determines if the derivation function uses the purpose byte.
Definition: pwdbased.h:56
size_t MaxDerivedKeyLength() const
Provides the maximum derived key length.
Definition: pwdbased.h:178
PBKDF1 from PKCS #5.
Definition: pwdbased.h:52
bool UsesPurposeByte() const
Determines if the derivation function uses the purpose byte.
Definition: pwdbased.h:179
size_t MaxDerivedKeyLength() const
Provides the maximum derived key length.
Definition: pwdbased.h:55
Classes for HMAC message authentication codes.
unsigned int DeriveKey(byte *derived, size_t derivedLen, byte purpose, const byte *password, size_t passwordLen, const byte *salt, size_t saltLen, unsigned int iterations, double timeInSeconds=0) const
Derive key from the password.
Definition: pwdbased.h:113
PBKDF from PKCS #12, appendix B.
Definition: pwdbased.h:175
unsigned int DigestSize() const
Provides the digest size of the hash.
Definition: hmac.h:28
bool UsesPurposeByte() const
Determines if the derivation function uses the purpose byte.
Definition: pwdbased.h:68
Multiple precision integer with arithmetic operations.
Definition: integer.h:31
void Update(const byte *input, size_t length)
Updates a hash with additional input.
Definition: hmac.cpp:60
const T & STDMIN(const T &a, const T &b)
Replacement function for std::min.
Definition: misc.h:450
virtual void CalculateDigest(byte *digest, const byte *input, size_t length)
Updates the hash with additional input and computes the hash of the current message.
Definition: cryptlib.h:997
HMAC.
Definition: hmac.h:50
void xorbuf(byte *buf, const byte *mask, size_t count)
Performs an XOR of a buffer with a mask.
Definition: misc.cpp:28
T1 RoundUpToMultipleOf(const T1 &n, const T2 &m)
Rounds a value up to a multiple of a second value.
Definition: misc.h:846
Crypto++ library namespace.
Measure CPU time spent executing instructions of this thread (if supported by OS) ...
Definition: hrtimer.h:48
virtual void Final(byte *digest)
Computes the hash of the current message.
Definition: cryptlib.h:954