include/cryptopp/scrypt.h

0001 // scrypt.h - written and placed in public domain by Jeffrey Walton.

0002 //            Based on reference source code by Colin Percival.

0003
0004 /// \file scrypt.h

0005 /// \brief Classes for Scrypt from RFC 7914

0006 /// \sa <A HREF="https://www.tarsnap.com/scrypt/scrypt.pdf">Stronger Key Derivation via

0007 ///   Sequential Memory-Hard Functions</a>,

0008 ///   <A HREF="https://www.tarsnap.com/scrypt.html">The scrypt key derivation function</A>

0009 ///   and <A HREF="https://tools.ietf.org/html/rfc7914">RFC 7914, The scrypt Password-Based

0010 ///   Key Derivation Function</A>

0011 /// \since Crypto++ 7.0

0012
0013 #ifndef CRYPTOPP_SCRYPT_H
0014 #define CRYPTOPP_SCRYPT_H
0015
0016 #include "cryptlib.h"
0017 #include "secblock.h"
0018
0019 NAMESPACE_BEGIN(CryptoPP)
0020
0021 /// \brief Scrypt key derivation function

0022 /// \details The Crypto++ implementation uses OpenMP to accelerate the derivation when

0023 ///   available.

0024 /// \details The Crypto++ implementation of Scrypt is limited by C++ datatypes. For

0025 ///   example, the library is limited to a derived key length of <tt>SIZE_MAX</tt>,

0026 ///   and not <tt>(2^32 - 1) * 32</tt>.

0027 /// \sa <A HREF="https://www.tarsnap.com/scrypt/scrypt.pdf">Stronger Key Derivation via

0028 ///   Sequential Memory-Hard Functions</A>,

0029 ///   <A HREF="https://www.tarsnap.com/scrypt.html">The scrypt key derivation function</A>

0030 ///   and <A HREF="https://tools.ietf.org/html/rfc7914">RFC 7914, The scrypt Password-Based

0031 ///   Key Derivation Function</A>

0032 /// \since Crypto++ 7.0

0033 class Scrypt : public KeyDerivationFunction
0034 {
0035 public:
0036     virtual ~Scrypt() {}
0037
0038     static std::string StaticAlgorithmName () {
0039         return "scrypt";
0040     }
0041
0042     // KeyDerivationFunction interface

0043     std::string AlgorithmName() const {
0044         return StaticAlgorithmName();
0045     }
0046
0047     // KeyDerivationFunction interface

0048     size_t MaxDerivedKeyLength() const {
0049         return static_cast<size_t>(0)-1;
0050     }
0051
0052     // KeyDerivationFunction interface

0053     size_t GetValidDerivedLength(size_t keylength) const;
0054
0055     // KeyDerivationFunction interface

0056     size_t DeriveKey(byte *derived, size_t derivedLen, const byte *secret, size_t secretLen,
0057         const NameValuePairs& params) const;
0058
0059     /// \brief Derive a key from a seed

0060     /// \param derived the derived output buffer

0061     /// \param derivedLen the size of the derived buffer, in bytes

0062     /// \param secret the seed input buffer

0063     /// \param secretLen the size of the secret buffer, in bytes

0064     /// \param salt the salt input buffer

0065     /// \param saltLen the size of the salt buffer, in bytes

0066     /// \param cost the CPU/memory cost factor

0067     /// \param blockSize the block size

0068     /// \param parallelization the parallelization factor

0069     /// \return the number of iterations performed

0070     /// \throw InvalidDerivedKeyLength if <tt>derivedLen</tt> is invalid for the scheme

0071     /// \details DeriveKey() provides a standard interface to derive a key from

0072     ///   a seed and other parameters. Each class that derives from KeyDerivationFunction

0073     ///   provides an overload that accepts most parameters used by the derivation function.

0074     /// \details The CPU/Memory <tt>cost</tt> parameter ("N" in the documents) must be

0075     ///   larger than 1, a power of 2, and less than <tt>2^(128 * r / 8)</tt>.

0076     /// \details The parameter <tt>blockSize</tt> ("r" in the documents) specifies the block

0077     ///   size.

0078     /// \details The <tt>parallelization</tt> parameter ("p" in the documents) is a positive

0079     ///   integer less than or equal to <tt>((2^32-1) * 32) / (128 * r)</tt>. Due to Microsoft

0080     ///   and its OpenMP 2.0 implementation <tt>parallelization</tt> is limited to

0081     ///   <tt>std::numeric_limits<int>::max()</tt>.

0082     /// \details Scrypt always returns 1 because it only performs 1 iteration. Other

0083     ///   derivation functions, like PBKDF's, will return more interesting values.

0084     /// \details The Crypto++ implementation of Scrypt is limited by C++ datatypes. For

0085     ///   example, the library is limited to a derived key length of <tt>SIZE_MAX</tt>,

0086     ///   and not <tt>(2^32 - 1) * 32</tt>.

0087     size_t DeriveKey(byte *derived, size_t derivedLen, const byte *secret, size_t secretLen,
0088         const byte *salt, size_t saltLen, word64 cost=2, word64 blockSize=8, word64 parallelization=1) const;
0089
0090 protected:
0091     enum {defaultCost=2, defaultBlockSize=8, defaultParallelization=1};
0092
0093     // KeyDerivationFunction interface

0094     const Algorithm & GetAlgorithm() const {
0095         return *this;
0096     }
0097
0098     inline void ValidateParameters(size_t derivedlen, word64 cost, word64 blockSize, word64 parallelization) const;
0099 };
0100
0101 NAMESPACE_END
0102
0103 #endif // CRYPTOPP_SCRYPT_H