Botan 3.0.0-alpha0
Crypto and TLS for C&
Public Member Functions | List of all members
Botan::Scrypt Class Referencefinal

#include <scrypt.h>

Inheritance diagram for Botan::Scrypt:
Botan::PasswordHash

Public Member Functions

void derive_key (uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len) const override
 
virtual void derive_key (uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len, const uint8_t ad[], size_t ad_len, const uint8_t key[], size_t key_len) const
 
size_t iterations () const override
 
size_t memory_param () const override
 
Scryptoperator= (const Scrypt &)=default
 
size_t parallelism () const override
 
 Scrypt (const Scrypt &other)=default
 
 Scrypt (size_t N, size_t r, size_t p)
 
std::string to_string () const override
 
size_t total_memory_usage () const override
 

Detailed Description

Scrypt key derivation function (RFC 7914)

Definition at line 20 of file scrypt.h.

Constructor & Destructor Documentation

◆ Scrypt() [1/2]

Botan::Scrypt::Scrypt ( size_t  N,
size_t  r,
size_t  p 
)

Definition at line 139 of file scrypt.cpp.

139 :
140 m_N(N), m_r(r), m_p(p)
141 {
142 if(!is_power_of_2(N))
143 throw Invalid_Argument("Scrypt N parameter must be a power of 2");
144
145 if(p == 0 || p > 1024)
146 throw Invalid_Argument("Invalid or unsupported scrypt p");
147 if(r == 0 || r > 256)
148 throw Invalid_Argument("Invalid or unsupported scrypt r");
149 if(N < 1 || N > 4194304)
150 throw Invalid_Argument("Invalid or unsupported scrypt N");
151 }
constexpr bool is_power_of_2(T arg)
Definition: bit_ops.h:43

◆ Scrypt() [2/2]

Botan::Scrypt::Scrypt ( const Scrypt other)
default

Member Function Documentation

◆ derive_key() [1/2]

void Botan::Scrypt::derive_key ( uint8_t  out[],
size_t  out_len,
const char *  password,
size_t  password_len,
const uint8_t  salt[],
size_t  salt_len 
) const
overridevirtual

Derive a new key under the current Scrypt parameter set

Implements Botan::PasswordHash.

Definition at line 223 of file scrypt.cpp.

226 {
227 const size_t N = memory_param();
228 const size_t p = parallelism();
229 const size_t r = iterations();
230
231 const size_t S = 128 * r;
232 secure_vector<uint8_t> B(p * S);
233 // temp space
234 secure_vector<uint8_t> V((N+1) * S);
235
236 auto hmac_sha256 = MessageAuthenticationCode::create_or_throw("HMAC(SHA-256)");
237
238 try
239 {
240 hmac_sha256->set_key(cast_char_ptr_to_uint8(password), password_len);
241 }
242 catch(Invalid_Key_Length&)
243 {
244 throw Invalid_Argument("Scrypt cannot accept passphrases of the provided length");
245 }
246
247 pbkdf2(*hmac_sha256.get(),
248 B.data(), B.size(),
249 salt, salt_len,
250 1);
251
252 // these can be parallel
253 for(size_t i = 0; i != p; ++i)
254 {
255 scryptROMmix(r, N, &B[128*r*i], V);
256 }
257
258 pbkdf2(*hmac_sha256.get(),
259 output, output_len,
260 B.data(), B.size(),
261 1);
262 }
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(const std::string &algo_spec, const std::string &provider="")
Definition: mac.cpp:134
size_t memory_param() const override
Definition: scrypt.h:41
size_t iterations() const override
Definition: scrypt.h:37
size_t parallelism() const override
Definition: scrypt.h:39
size_t pbkdf2(MessageAuthenticationCode &prf, uint8_t out[], size_t out_len, const std::string &password, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec)
Definition: pbkdf2.cpp:34
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition: mem_ops.h:183
size_t salt_len
Definition: x509_obj.cpp:25

◆ derive_key() [2/2]

void Botan::PasswordHash::derive_key ( uint8_t  out[],
size_t  out_len,
const char *  password,
size_t  password_len,
const uint8_t  salt[],
size_t  salt_len,
const uint8_t  ad[],
size_t  ad_len,
const uint8_t  key[],
size_t  key_len 
) const
virtualinherited

Derive a key from a password plus additional data and/or a secret key

Currently this is only supported for Argon2. Using a non-empty AD or key with other algorithms will cause a Not_Implemented exception.

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passwordthe password to derive the key from
password_lenthe length of password in bytes
salta randomly chosen salt
salt_lenlength of salt in bytes
adsome additional data
ad_lenlength of ad in bytes
keya secret key
key_lenlength of key in bytes

This function is const, but is not thread safe. Different threads should either use unique objects, or serialize all access.

Reimplemented in Botan::Argon2.

Definition at line 33 of file pwdhash.cpp.

38 {
39 BOTAN_UNUSED(ad, key);
40
41 if(ad_len == 0 && key_len == 0)
42 return this->derive_key(out, out_len,
43 password, password_len,
44 salt, salt_len);
45 else
46 throw Not_Implemented("PasswordHash " + this->to_string() + " does not support AD or key");
47 }
#define BOTAN_UNUSED(...)
Definition: assert.h:141
virtual void derive_key(uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len) const =0
virtual std::string to_string() const =0

References BOTAN_UNUSED, Botan::PasswordHash::derive_key(), salt_len, and Botan::PasswordHash::to_string().

◆ iterations()

size_t Botan::Scrypt::iterations ( ) const
inlineoverridevirtual

Most password hashes have some notion of iterations.

Implements Botan::PasswordHash.

Definition at line 37 of file scrypt.h.

37{ return m_r; }

◆ memory_param()

size_t Botan::Scrypt::memory_param ( ) const
inlineoverridevirtual

Some password hashing algorithms have a parameter which controls how much memory is used. If not supported by some algorithm, returns 0.

Reimplemented from Botan::PasswordHash.

Definition at line 41 of file scrypt.h.

41{ return m_N; }

◆ operator=()

Scrypt & Botan::Scrypt::operator= ( const Scrypt )
default

◆ parallelism()

size_t Botan::Scrypt::parallelism ( ) const
inlineoverridevirtual

Some password hashing algorithms have a parallelism parameter. If the algorithm does not support this notion, then the function returns zero. This allows distinguishing between a password hash which just does not support parallel operation, vs one that does support parallel operation but which has been configured to use a single lane.

Reimplemented from Botan::PasswordHash.

Definition at line 39 of file scrypt.h.

39{ return m_p; }

◆ to_string()

std::string Botan::Scrypt::to_string ( ) const
overridevirtual

Implements Botan::PasswordHash.

Definition at line 153 of file scrypt.cpp.

154 {
155 std::string out;
156 out = "Scrypt(";
157 out += std::to_string(m_N);
158 out += ",";
159 out += std::to_string(m_r);
160 out += ",";
161 out += std::to_string(m_p);
162 out += ")";
163 return out;
164 }
std::string to_string(const BER_Object &obj)
Definition: asn1_obj.cpp:209

References Botan::ASN1::to_string().

◆ total_memory_usage()

size_t Botan::Scrypt::total_memory_usage ( ) const
overridevirtual

Returns an estimate of the total number of bytes required to perform this key derivation.

If this algorithm uses a small and constant amount of memory, with no effort made towards being memory hard, this function returns 0.

Reimplemented from Botan::PasswordHash.

Definition at line 166 of file scrypt.cpp.

167 {
168 const size_t N = memory_param();
169 const size_t p = parallelism();
170 const size_t r = iterations();
171
172 return scrypt_memory_usage(N, r, p);
173 }

The documentation for this class was generated from the following files: