Crypto++  8.5
Free C++ class library of cryptographic schemes
scrypt.h
Go to the documentation of this file.
1 // scrypt.h - written and placed in public domain by Jeffrey Walton.
2 // Based on reference source code by Colin Percival.
3 
4 /// \file scrypt.h
5 /// \brief Classes for Scrypt from RFC 7914
6 /// \sa <A HREF="https://www.tarsnap.com/scrypt/scrypt.pdf">Stronger Key Derivation via
7 /// Sequential Memory-Hard Functions</a>,
8 /// <A HREF="https://www.tarsnap.com/scrypt.html">The scrypt key derivation function</A>
9 /// and <A HREF="https://tools.ietf.org/html/rfc7914">RFC 7914, The scrypt Password-Based
10 /// Key Derivation Function</A>
11 /// \since Crypto++ 7.0
12 
13 #ifndef CRYPTOPP_SCRYPT_H
14 #define CRYPTOPP_SCRYPT_H
15 
16 #include "cryptlib.h"
17 #include "secblock.h"
18 
19 NAMESPACE_BEGIN(CryptoPP)
20 
21 /// \brief Scrypt key derivation function
22 /// \details The Crypto++ implementation uses OpenMP to accelerate the derivation when
23 /// available.
24 /// \details The Crypto++ implementation of Scrypt is limited by C++ datatypes. For
25 /// example, the library is limited to a derived key length of <tt>SIZE_MAX</tt>,
26 /// and not <tt>(2^32 - 1) * 32</tt>.
27 /// \sa <A HREF="https://www.tarsnap.com/scrypt/scrypt.pdf">Stronger Key Derivation via
28 /// Sequential Memory-Hard Functions</A>,
29 /// <A HREF="https://www.tarsnap.com/scrypt.html">The scrypt key derivation function</A>
30 /// and <A HREF="https://tools.ietf.org/html/rfc7914">RFC 7914, The scrypt Password-Based
31 /// Key Derivation Function</A>
32 /// \since Crypto++ 7.0
34 {
35 public:
36  virtual ~Scrypt() {}
37 
38  static std::string StaticAlgorithmName () {
39  return "scrypt";
40  }
41 
42  // KeyDerivationFunction interface
43  std::string AlgorithmName() const {
44  return StaticAlgorithmName();
45  }
46 
47  // KeyDerivationFunction interface
48  size_t MaxDerivedKeyLength() const {
49  return static_cast<size_t>(0)-1;
50  }
51 
52  // KeyDerivationFunction interface
53  size_t GetValidDerivedLength(size_t keylength) const;
54 
55  // KeyDerivationFunction interface
56  size_t DeriveKey(byte *derived, size_t derivedLen, const byte *secret, size_t secretLen,
57  const NameValuePairs& params) const;
58 
59  /// \brief Derive a key from a seed
60  /// \param derived the derived output buffer
61  /// \param derivedLen the size of the derived buffer, in bytes
62  /// \param secret the seed input buffer
63  /// \param secretLen the size of the secret buffer, in bytes
64  /// \param salt the salt input buffer
65  /// \param saltLen the size of the salt buffer, in bytes
66  /// \param cost the CPU/memory cost factor
67  /// \param blockSize the block size
68  /// \param parallelization the parallelization factor
69  /// \return the number of iterations performed
70  /// \throw InvalidDerivedKeyLength if <tt>derivedLen</tt> is invalid for the scheme
71  /// \details DeriveKey() provides a standard interface to derive a key from
72  /// a seed and other parameters. Each class that derives from KeyDerivationFunction
73  /// provides an overload that accepts most parameters used by the derivation function.
74  /// \details The CPU/Memory <tt>cost</tt> parameter ("N" in the documents) must be
75  /// larger than 1, a power of 2, and less than <tt>2^(128 * r / 8)</tt>.
76  /// \details The parameter <tt>blockSize</tt> ("r" in the documents) specifies the block
77  /// size.
78  /// \details The <tt>parallelization</tt> parameter ("p" in the documents) is a positive
79  /// integer less than or equal to <tt>((2^32-1) * 32) / (128 * r)</tt>. Due to Microsoft
80  /// and its OpenMP 2.0 implementation <tt>parallelization</tt> is limited to
81  /// <tt>std::numeric_limits<int>::max()</tt>.
82  /// \details Scrypt always returns 1 because it only performs 1 iteration. Other
83  /// derivation functions, like PBKDF's, will return more interesting values.
84  /// \details The Crypto++ implementation of Scrypt is limited by C++ datatypes. For
85  /// example, the library is limited to a derived key length of <tt>SIZE_MAX</tt>,
86  /// and not <tt>(2^32 - 1) * 32</tt>.
87  size_t DeriveKey(byte *derived, size_t derivedLen, const byte *secret, size_t secretLen,
88  const byte *salt, size_t saltLen, word64 cost=2, word64 blockSize=8, word64 parallelization=1) const;
89 
90 protected:
91  enum {defaultCost=2, defaultBlockSize=8, defaultParallelization=1};
92 
93  // KeyDerivationFunction interface
94  const Algorithm & GetAlgorithm() const {
95  return *this;
96  }
97 
98  inline void ValidateParameters(size_t derivedlen, word64 cost, word64 blockSize, word64 parallelization) const;
99 };
100 
101 NAMESPACE_END
102 
103 #endif // CRYPTOPP_SCRYPT_H
Algorithm
Interface for all crypto algorithms.
Definition: cryptlib.h:598
Scrypt::AlgorithmName
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition: scrypt.h:43
secblock.h
Classes and functions for secure memory allocations.
word64
unsigned long long word64
64-bit unsigned datatype
Definition: config_int.h:91
KeyDerivationFunction
Interface for key derivation functions.
Definition: cryptlib.h:1522
CryptoPP
Crypto++ library namespace.
Scrypt::MaxDerivedKeyLength
size_t MaxDerivedKeyLength() const
Determine maximum number of bytes.
Definition: scrypt.h:48
Scrypt
Scrypt key derivation function.
Definition: scrypt.h:33
NameValuePairs
Interface for retrieving values given their names.
Definition: cryptlib.h:321
cryptlib.h
Abstract base classes that provide a uniform interface to this library.