Botan  1.11.15
src/lib/pbkdf/pbkdf.h
Go to the documentation of this file.
00001 /*
00002 * PBKDF
00003 * (C) 1999-2007,2012,2015 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_PBKDF_H__
00009 #define BOTAN_PBKDF_H__
00010 
00011 #include <botan/symkey.h>
00012 #include <botan/scan_name.h>
00013 #include <chrono>
00014 
00015 namespace Botan {
00016 
00017 /**
00018 * Base class for PBKDF (password based key derivation function)
00019 * implementations. Converts a password into a key using a salt
00020 * and iterated hashing to make brute force attacks harder.
00021 */
00022 class BOTAN_DLL PBKDF
00023    {
00024    public:
00025 
00026       virtual ~PBKDF() {}
00027 
00028       typedef SCAN_Name Spec;
00029 
00030       /**
00031       * @return new instance of this same algorithm
00032       */
00033       virtual PBKDF* clone() const = 0;
00034 
00035       virtual std::string name() const = 0;
00036 
00037       /**
00038       * Derive a key from a passphrase for a number of iterations
00039       * specified by either iterations or if iterations == 0 then
00040       * running until seconds time has elapsed.
00041       *
00042       * @param out_len the desired length of the key to produce
00043       * @param passphrase the password to derive the key from
00044       * @param salt a randomly chosen salt
00045       * @param salt_len length of salt in bytes
00046       * @param iterations the number of iterations to use (use 10K or more)
00047       * @param msec if iterations is zero, then instead the PBKDF is
00048       *        run until msec milliseconds has passed.
00049       * @return the number of iterations performed
00050       */
00051       virtual size_t pbkdf(byte out[], size_t out_len,
00052                            const std::string& passphrase,
00053                            const byte salt[], size_t salt_len,
00054                            size_t iterations,
00055                            std::chrono::milliseconds msec) const = 0;
00056 
00057       void pbkdf_iterations(byte out[], size_t out_len,
00058                             const std::string& passphrase,
00059                             const byte salt[], size_t salt_len,
00060                             size_t iterations) const;
00061 
00062       void pbkdf_timed(byte out[], size_t out_len,
00063                          const std::string& passphrase,
00064                          const byte salt[], size_t salt_len,
00065                          std::chrono::milliseconds msec,
00066                          size_t& iterations) const;
00067 
00068       secure_vector<byte> pbkdf_iterations(size_t out_len,
00069                                            const std::string& passphrase,
00070                                            const byte salt[], size_t salt_len,
00071                                            size_t iterations) const;
00072 
00073       secure_vector<byte> pbkdf_timed(size_t out_len,
00074                                       const std::string& passphrase,
00075                                       const byte salt[], size_t salt_len,
00076                                       std::chrono::milliseconds msec,
00077                                       size_t& iterations) const;
00078 
00079       // Following kept for compat with 1.10:
00080 
00081       /**
00082       * Derive a key from a passphrase
00083       * @param out_len the desired length of the key to produce
00084       * @param passphrase the password to derive the key from
00085       * @param salt a randomly chosen salt
00086       * @param salt_len length of salt in bytes
00087       * @param iterations the number of iterations to use (use 10K or more)
00088       */
00089       OctetString derive_key(size_t out_len,
00090                              const std::string& passphrase,
00091                              const byte salt[], size_t salt_len,
00092                              size_t iterations) const
00093          {
00094          return pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations);
00095          }
00096 
00097       /**
00098       * Derive a key from a passphrase
00099       * @param out_len the desired length of the key to produce
00100       * @param passphrase the password to derive the key from
00101       * @param salt a randomly chosen salt
00102       * @param iterations the number of iterations to use (use 10K or more)
00103       */
00104       template<typename Alloc>
00105       OctetString derive_key(size_t out_len,
00106                              const std::string& passphrase,
00107                              const std::vector<byte, Alloc>& salt,
00108                              size_t iterations) const
00109          {
00110          return pbkdf_iterations(out_len, passphrase, &salt[0], salt.size(), iterations);
00111          }
00112 
00113       /**
00114       * Derive a key from a passphrase
00115       * @param out_len the desired length of the key to produce
00116       * @param passphrase the password to derive the key from
00117       * @param salt a randomly chosen salt
00118       * @param salt_len length of salt in bytes
00119       * @param msec is how long to run the PBKDF
00120       * @param iterations is set to the number of iterations used
00121       */
00122       OctetString derive_key(size_t out_len,
00123                              const std::string& passphrase,
00124                              const byte salt[], size_t salt_len,
00125                              std::chrono::milliseconds msec,
00126                              size_t& iterations) const
00127          {
00128          return pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations);
00129          }
00130 
00131       /**
00132       * Derive a key from a passphrase using a certain amount of time
00133       * @param out_len the desired length of the key to produce
00134       * @param passphrase the password to derive the key from
00135       * @param salt a randomly chosen salt
00136       * @param msec is how long to run the PBKDF
00137       * @param iterations is set to the number of iterations used
00138       */
00139       template<typename Alloc>
00140       OctetString derive_key(size_t out_len,
00141                              const std::string& passphrase,
00142                              const std::vector<byte, Alloc>& salt,
00143                              std::chrono::milliseconds msec,
00144                              size_t& iterations) const
00145          {
00146          return pbkdf_timed(out_len, passphrase, &salt[0], salt.size(), msec, iterations);
00147          }
00148    };
00149 
00150 }
00151 
00152 #endif