Botan 3.0.0
Crypto and TLS for C&
Public Member Functions | Static Public Member Functions | List of all members
Botan::Argon2 Class Referencefinal

#include <argon2.h>

Inheritance diagram for Botan::Argon2:
Botan::PasswordHash

Public Member Functions

 Argon2 (const Argon2 &other)=default
 
 Argon2 (uint8_t family, size_t M, size_t t, size_t p)
 
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 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 override
 
void hash (std::span< uint8_t > out, std::string_view password, std::span< const uint8_t > salt)
 
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)
 
size_t iterations () const override
 
size_t M () const
 
size_t memory_param () const override
 
Argon2operator= (const Argon2 &)=default
 
size_t p () const
 
size_t parallelism () const override
 
bool supports_associated_data () const override
 
bool supports_keyed_operation () const override
 
size_t t () const
 
std::string to_string () const override
 
size_t total_memory_usage () const override
 

Static Public Member Functions

static void blamka (uint64_t N[128], uint64_t T[128])
 

Detailed Description

Argon2 key derivation function

Definition at line 26 of file argon2.h.

Constructor & Destructor Documentation

◆ Argon2() [1/2]

Botan::Argon2::Argon2 ( uint8_t  family,
size_t  M,
size_t  t,
size_t  p 
)

Definition at line 15 of file argon2pwhash.cpp.

15 :
16 m_family(family),
17 m_M(M),
18 m_t(t),
19 m_p(p)
20 {
21 BOTAN_ARG_CHECK(m_p >= 1 && m_p <= 128, "Invalid Argon2 threads parameter");
22 BOTAN_ARG_CHECK(m_M >= 8*m_p && m_M <= 8192*1024, "Invalid Argon2 M parameter");
23 BOTAN_ARG_CHECK(m_t >= 1, "Invalid Argon2 t parameter");
24 }
#define BOTAN_ARG_CHECK(expr, msg)
Definition: assert.h:36
size_t p() const
Definition: argon2.h:51
size_t t() const
Definition: argon2.h:50
size_t M() const
Definition: argon2.h:49

References BOTAN_ARG_CHECK.

◆ Argon2() [2/2]

Botan::Argon2::Argon2 ( const Argon2 other)
default

Member Function Documentation

◆ blamka()

void Botan::Argon2::blamka ( uint64_t  N[128],
uint64_t  T[128] 
)
static

Argon2's BLAMKA function

Definition at line 179 of file argon2.cpp.

180 {
181#if defined(BOTAN_HAS_ARGON2_AVX2)
182 if(CPUID::has_avx2())
183 return Argon2::blamka_avx2(N, T);
184#endif
185
186#if defined(BOTAN_HAS_ARGON2_SSSE3)
187 if(CPUID::has_ssse3())
188 return Argon2::blamka_ssse3(N, T);
189#endif
190
191 copy_mem(T, N, 128);
192
193 for(size_t i = 0; i != 128; i += 16)
194 {
195 blamka_G(T[i+ 0], T[i+ 4], T[i+ 8], T[i+ 12]);
196 blamka_G(T[i+ 1], T[i+ 5], T[i+ 9], T[i+ 13]);
197 blamka_G(T[i+ 2], T[i+ 6], T[i+ 10], T[i+ 14]);
198 blamka_G(T[i+ 3], T[i+ 7], T[i+ 11], T[i+ 15]);
199
200 blamka_G(T[i+ 0], T[i+ 5], T[i+ 10], T[i+ 15]);
201 blamka_G(T[i+ 1], T[i+ 6], T[i+ 11], T[i+ 12]);
202 blamka_G(T[i+ 2], T[i+ 7], T[i+ 8], T[i+ 13]);
203 blamka_G(T[i+ 3], T[i+ 4], T[i+ 9], T[i+ 14]);
204 }
205
206 for(size_t i = 0; i != 128 / 8; i += 2)
207 {
208 blamka_G(T[i+ 0], T[i+ 32], T[i+ 64], T[i+ 96]);
209 blamka_G(T[i+ 1], T[i+ 33], T[i+ 65], T[i+ 97]);
210 blamka_G(T[i+ 16], T[i+ 48], T[i+ 80], T[i+112]);
211 blamka_G(T[i+ 17], T[i+ 49], T[i+ 81], T[i+113]);
212
213 blamka_G(T[i+ 0], T[i+ 33], T[i+ 80], T[i+113]);
214 blamka_G(T[i+ 1], T[i+ 48], T[i+ 81], T[i+ 96]);
215 blamka_G(T[i+ 16], T[i+ 49], T[i+ 64], T[i+ 97]);
216 blamka_G(T[i+ 17], T[i+ 32], T[i+ 65], T[i+112]);
217 }
218
219 for(size_t i = 0; i != 128; ++i)
220 N[i] ^= T[i];
221 }
FE_25519 T
Definition: ge.cpp:36
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:126

References Botan::copy_mem(), and T.

◆ derive_key() [1/2]

void Botan::Argon2::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 Argon2 parameter set

Implements Botan::PasswordHash.

Definition at line 26 of file argon2pwhash.cpp.

29 {
30 argon2(output, output_len,
31 password, password_len,
32 salt, salt_len,
33 nullptr, 0,
34 nullptr, 0);
35 }

◆ derive_key() [2/2]

void Botan::Argon2::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
overridevirtual

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 from Botan::PasswordHash.

Definition at line 37 of file argon2pwhash.cpp.

42 {
43 argon2(output, output_len,
44 password, password_len,
45 salt, salt_len,
46 key, key_len,
47 ad, ad_len);
48 }

◆ hash() [1/2]

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

Hash a password into a bitstring

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 82 of file pwdhash.h.

85 {
86 this->derive_key(out.data(), out.size(),
87 password.data(), password.size(),
88 salt.data(), salt.size());
89 }
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

◆ 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 
)
inlineinherited

Hash a password into a bitstring

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 103 of file pwdhash.h.

108 {
109 this->derive_key(out.data(), out.size(),
110 password.data(), password.size(),
111 salt.data(), salt.size(),
112 associated_data.data(), associated_data.size(),
113 key.data(), key.size());
114 }

◆ iterations()

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

Most password hashes have some notion of iterations.

Implements Botan::PasswordHash.

Definition at line 57 of file argon2.h.

57{ return t(); }

◆ M()

size_t Botan::Argon2::M ( ) const
inline

Definition at line 49 of file argon2.h.

49{ return m_M; }

◆ memory_param()

size_t Botan::Argon2::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 61 of file argon2.h.

61{ return M(); }

◆ operator=()

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

◆ p()

size_t Botan::Argon2::p ( ) const
inline

Definition at line 51 of file argon2.h.

51{ return m_p; }

◆ parallelism()

size_t Botan::Argon2::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 59 of file argon2.h.

59{ return p(); }

◆ supports_associated_data()

bool Botan::Argon2::supports_associated_data ( ) const
inlineoverridevirtual

Returns true if this password hash supports supplying associated data

Reimplemented from Botan::PasswordHash.

Definition at line 55 of file argon2.h.

55{ return true; }

◆ supports_keyed_operation()

bool Botan::Argon2::supports_keyed_operation ( ) const
inlineoverridevirtual

Returns true if this password hash supports supplying a key

Reimplemented from Botan::PasswordHash.

Definition at line 53 of file argon2.h.

53{ return true; }

◆ t()

size_t Botan::Argon2::t ( ) const
inline

Definition at line 50 of file argon2.h.

50{ return m_t; }

◆ to_string()

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

Implements Botan::PasswordHash.

Definition at line 69 of file argon2pwhash.cpp.

70 {
71 return fmt("{}({},{},{})",
72 argon2_family_name(m_family),
73 m_M, m_t, m_p);
74 }
std::string fmt(std::string_view format, const T &... args)
Definition: fmt.h:60

References Botan::fmt().

◆ total_memory_usage()

size_t Botan::Argon2::total_memory_usage ( ) const
inlineoverridevirtual

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 63 of file argon2.h.

63{ return M() * 1024; }

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