Botan::Scrypt Class Reference

#include <scrypt.h>

Inheritance diagram for Botan::Scrypt:

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

                                           : m_N(N), m_r(r), m_p(p) {
   if(!is_power_of_2(N)) {
      throw Invalid_Argument("Scrypt N parameter must be a power of 2");
   }
 
   if(p == 0 || p > 1024) {
      throw Invalid_Argument("Invalid or unsupported scrypt p");
   }
   if(r == 0 || r > 256) {
      throw Invalid_Argument("Invalid or unsupported scrypt r");
   }
   if(N < 1 || N > MAX_SCRYPT_N) {
      throw Invalid_Argument("Invalid or unsupported scrypt N");
   }
 
   if(const auto memory_usage = scrypt_memory_usage(N, r, p)) {
      if(memory_usage > MAX_SCRYPT_MEMORY_BYTES) {
         throw Invalid_Argument("Scrypt parameters exceed maximum allowed memory limit");
      }
   } else {
      throw Invalid_Argument("Scrypt parameters are too large for this platform");
   }
}

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

out	buffer to store the derived key, must be of out_len bytes
out_len	the desired length of the key to produce
password	the password to derive the key from
password_len	the length of password in bytes
salt	a randomly chosen salt
salt_len	length of salt in bytes
ad	some additional data
ad_len	length of ad in bytes
key	a secret key
key_len	length 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 39 of file pwdhash.cpp.

                                                    {
   BOTAN_UNUSED(ad, key);
 
   if(ad_len == 0 && key_len == 0) {
      return this->derive_key(out, out_len, password, password_len, salt, salt_len);
   } else {
      throw Not_Implemented("PasswordHash " + this->to_string() + " does not support AD or key");
   }
}

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

                                               {
   if(output_len == 0) {
      return;
   }
 
   const size_t N = memory_param();
   const size_t p = parallelism();
   const size_t r = iterations();
 
   const size_t S = mul_or_throw(size_t(128), r, "Scrypt S size overflow");
   secure_vector<uint8_t> B(mul_or_throw(p, S, "Scrypt B size overflow"));
   // temp space
   secure_vector<uint8_t> V(mul_or_throw(N + 1, S, "Scrypt V size overflow"));
 
   auto hmac_sha256 = MessageAuthenticationCode::create_or_throw("HMAC(SHA-256)");
 
   try {
      hmac_sha256->set_key(as_span_of_bytes(password, password_len));
   } catch(Invalid_Key_Length&) {
      throw Invalid_Argument("Scrypt cannot accept passphrases of the provided length");
   }
 
   pbkdf2(*hmac_sha256, B.data(), B.size(), salt, salt_len, 1);
 
   // these can be parallel
   for(size_t i = 0; i != p; ++i) {
      scryptROMmix(r, N, &B[128 * r * i], V);
   }
 
   pbkdf2(*hmac_sha256, output, output_len, B.data(), B.size(), 1);
}

References Botan::as_span_of_bytes(), Botan::MessageAuthenticationCode::create_or_throw(), iterations(), memory_param(), Botan::mul_or_throw(), 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

out	a span where the derived key will be placed
password	the password to derive the key from
salt	a 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 95 of file pwdhash.h.

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

References derive_key().

Referenced by Botan::PKCS12_KDF::PKCS12_KDF(), and 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

out	a span where the derived key will be placed
password	the password to derive the key from
salt	a randomly chosen salt
associated_data	some additional data
key	a 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 116 of file pwdhash.h.

                                                  {
         this->derive_key(out.data(),
                          out.size(),
                          password.data(),
                          password.size(),
                          salt.data(),
                          salt.size(),
                          associated_data.data(),
                          associated_data.size(),
                          key.data(),
                          key.size());
      }

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.

{ 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.

{ 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.

{ return m_p; }

Referenced by derive_key(), and total_memory_usage().

supports_associated_data()

virtual bool Botan::PasswordHash::supports_associated_data ( ) const

inlinevirtualinherited

Query if this password hash supports associated data

Returns

true if this password hash supports supplying associated data

Reimplemented in Botan::Argon2.

Definition at line 80 of file pwdhash.h.

{ return false; }

supports_keyed_operation()

virtual bool Botan::PasswordHash::supports_keyed_operation ( ) const

inlinevirtualinherited

Query if this password hash supports a symmetric key

Returns

true if this password hash supports supplying a key

Reimplemented in Botan::Argon2.

Definition at line 73 of file pwdhash.h.

{ return false; }

to_string()

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

overridevirtual

Return a free-form string identifying the algorithm and parameters

Implements Botan::PasswordHash.

Definition at line 177 of file scrypt.cpp.

                                  {
   return fmt("Scrypt({},{},{})", m_N, m_r, m_p);
}

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

                                        {
   const size_t N = memory_param();
   const size_t p = parallelism();
   const size_t r = iterations();
 
   const auto consumption = scrypt_memory_usage(N, r, p);
   BOTAN_ASSERT_NOMSG(consumption.has_value());
   return consumption.value();
}

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

---

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

• src/lib/pbkdf/scrypt/scrypt.h
• src/lib/pbkdf/scrypt/scrypt.cpp