Botan 3.9.0
Crypto and TLS for C&
Botan::Scrypt Class Referencefinal

#include <scrypt.h>

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

Public Member Functions

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
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
void hash (std::span< uint8_t > out, std::string_view password, std::span< const uint8_t > salt) const
void hash (std::span< uint8_t > out, std::string_view password, std::span< const uint8_t > salt, std::span< const uint8_t > associated_data, std::span< const uint8_t > key) const
size_t iterations () const override
size_t memory_param () const override
size_t parallelism () const override
 Scrypt (size_t N, size_t r, size_t p)
virtual bool supports_associated_data () const
virtual bool supports_keyed_operation () const
std::string to_string () const override
size_t total_memory_usage () const override

Detailed Description

Scrypt key derivation function (RFC 7914)

Definition at line 21 of file scrypt.h.

Constructor & Destructor Documentation

◆ Scrypt()

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

Definition at line 127 of file scrypt.cpp.

127 : m_N(N), m_r(r), m_p(p) {
128 if(!is_power_of_2(N)) {
129 throw Invalid_Argument("Scrypt N parameter must be a power of 2");
130 }
131
132 if(p == 0 || p > 1024) {
133 throw Invalid_Argument("Invalid or unsupported scrypt p");
134 }
135 if(r == 0 || r > 256) {
136 throw Invalid_Argument("Invalid or unsupported scrypt r");
137 }
138 if(N < 1 || N > 4194304) {
139 throw Invalid_Argument("Invalid or unsupported scrypt N");
140 }
141}
BOTAN_FORCE_INLINE constexpr bool is_power_of_2(T arg)
Definition bit_ops.h:45

References Botan::is_power_of_2().

Member Function Documentation

◆ derive_key() [1/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 35 of file pwdhash.cpp.

44 {
45 BOTAN_UNUSED(ad, key);
46
47 if(ad_len == 0 && key_len == 0) {
48 return this->derive_key(out, out_len, password, password_len, salt, salt_len);
49 } else {
50 throw Not_Implemented("PasswordHash " + this->to_string() + " does not support AD or key");
51 }
52}
#define BOTAN_UNUSED
Definition assert.h:144
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, derive_key(), and to_string().

◆ derive_key() [2/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 196 of file scrypt.cpp.

201 {
202 const size_t N = memory_param();
203 const size_t p = parallelism();
204 const size_t r = iterations();
205
206 const size_t S = 128 * r;
207 secure_vector<uint8_t> B(p * S);
208 // temp space
209 secure_vector<uint8_t> V((N + 1) * S);
210
211 auto hmac_sha256 = MessageAuthenticationCode::create_or_throw("HMAC(SHA-256)");
212
213 try {
214 hmac_sha256->set_key(as_span_of_bytes(password, password_len));
215 } catch(Invalid_Key_Length&) {
216 throw Invalid_Argument("Scrypt cannot accept passphrases of the provided length");
217 }
218
219 pbkdf2(*hmac_sha256, B.data(), B.size(), salt, salt_len, 1);
220
221 // these can be parallel
222 for(size_t i = 0; i != p; ++i) {
223 scryptROMmix(r, N, &B[128 * r * i], V);
224 }
225
226 pbkdf2(*hmac_sha256, output, output_len, B.data(), B.size(), 1);
227}
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:148
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
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
Definition mem_utils.h:28
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69
size_t pbkdf2(MessageAuthenticationCode &prf, uint8_t out[], size_t out_len, std::string_view password, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec)
Definition pbkdf2.cpp:72

References Botan::as_span_of_bytes(), Botan::MessageAuthenticationCode::create_or_throw(), iterations(), memory_param(), parallelism(), and Botan::pbkdf2().

◆ hash() [1/2]

void Botan::PasswordHash::hash ( std::span< uint8_t > out,
std::string_view password,
std::span< const uint8_t > salt ) const
inlineinherited

Hash a password into a bitstring

Derive a key from the specified password and salt, placing it into out.

Parameters
outa span where the derived key will be placed
passwordthe password to derive the key from
salta randomly chosen salt

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

Definition at line 84 of file pwdhash.h.

84 {
85 this->derive_key(out.data(), out.size(), password.data(), password.size(), salt.data(), salt.size());
86 }

References derive_key().

Referenced by Botan::RFC4880_S2K::RFC4880_S2K().

◆ hash() [2/2]

void Botan::PasswordHash::hash ( std::span< uint8_t > out,
std::string_view password,
std::span< const uint8_t > salt,
std::span< const uint8_t > associated_data,
std::span< const uint8_t > key ) const
inlineinherited

Hash a password into a bitstring

Derive a key from the specified password, salt, associated_data, and secret key, placing it into out. The associated_data and key are both allowed to be empty. Currently non-empty AD/key is only supported with Argon2.

Parameters
outa span where the derived key will be placed
passwordthe password to derive the key from
salta randomly chosen salt
associated_datasome additional data
keya secret key

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

Definition at line 105 of file pwdhash.h.

109 {
110 this->derive_key(out.data(),
111 out.size(),
112 password.data(),
113 password.size(),
114 salt.data(),
115 salt.size(),
116 associated_data.data(),
117 associated_data.size(),
118 key.data(),
119 key.size());
120 }

References derive_key().

◆ 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; }

Referenced by derive_key(), and total_memory_usage().

◆ 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; }

Referenced by derive_key(), and total_memory_usage().

◆ 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; }

Referenced by derive_key(), and total_memory_usage().

◆ supports_associated_data()

virtual bool Botan::PasswordHash::supports_associated_data ( ) const
inlinevirtualinherited
Returns
true if this password hash supports supplying associated data

Reimplemented in Botan::Argon2.

Definition at line 69 of file pwdhash.h.

69{ return false; }

◆ supports_keyed_operation()

virtual bool Botan::PasswordHash::supports_keyed_operation ( ) const
inlinevirtualinherited
Returns
true if this password hash supports supplying a key

Reimplemented in Botan::Argon2.

Definition at line 64 of file pwdhash.h.

64{ return false; }

◆ to_string()

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

Implements Botan::PasswordHash.

Definition at line 143 of file scrypt.cpp.

143 {
144 return fmt("Scrypt({},{},{})", m_N, m_r, m_p);
145}
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References Botan::fmt().

◆ 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 147 of file scrypt.cpp.

147 {
148 const size_t N = memory_param();
149 const size_t p = parallelism();
150 const size_t r = iterations();
151
152 return scrypt_memory_usage(N, r, p);
153}

References iterations(), memory_param(), and parallelism().


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