Class to handle caching_sha2_authentication Provides methods for: More...

#include <i_sha2_password.h>

Public Member Functions
	Caching_sha2_password (MYSQL_PLUGIN plugin_handle, size_t stored_digest_rounds, Stored_digest_info digest_type=Stored_digest_info::CRYPT5, unsigned int fast_digest_rounds=DEFAULT_FAST_DIGEST_ROUNDS, bool enforce_storage_format=false)
	Caching_sha2_password constructor - Initializes rw lock. More...

	~Caching_sha2_password ()
	Caching_sha2_password destructor - destroy rw lock. More...

std::pair< bool, bool >	authenticate (const std::string &authorization_id, const std::string_view *serialized_string, const std::string &plaintext_password, bool &set_password_expired_flag)
	Perform slow authentication. More...

std::pair< bool, bool >	fast_authenticate (const std::string &authorization_id, const unsigned char random, unsigned int random_length, const unsigned char scramble, bool check_second)
	Perform fast authentication. More...

void	remove_cached_entry (const std::string &authorization_id)
	Remove an entry from the cache. More...

bool	deserialize (const std::string_view &serialized_string, Stored_digest_info &digest_type, std::string &salt, std::string &digest, size_t &iterations)
	Deserialize obtained hash and retrieve various parts. More...

bool	serialize (std::string &serialized_string, const Stored_digest_info &digest_type, const std::string &salt, const std::string &digest, size_t iterations)
	Serialize following: a. More...

bool	generate_fast_digest (const std::string &plaintext_password, sha2_cache_entry &digest, unsigned int loc)
	Generate digest based on get_fast_digest_rounds() More...

std::pair< bool, bool >	compare_against_stored (const std::string &src, const std::string_view &stored, const std::optional< std::string > &authorization_id, Stored_digest_info &digest_type)

bool	generate_stored_digest (const std::string &src, std::string &serialized_string)

size_t	get_cache_count ()
	Get cache count. More...

void	clear_cache ()
	Clear the password cache. More...

bool	validate_hash (const std::string &serialized_string)
	Validate a hash format. More...

Stored_digest_info	get_stored_digest_type () const

void	set_stored_digest_type (Stored_digest_info digest_type)

size_t	get_stored_digest_rounds ()

void	set_stored_digest_rounds (size_t stored_digest_rounds)

bool	get_enforce_storage_format ()

void	set_enforce_storage_format (bool value)

unsigned int	get_fast_digest_rounds ()

Protected Member Functions
bool	generate_crypt5 (const std::string &source, const std::string &salt, std::string &digest, unsigned int iterations)
	Generate multi-round sha2 hash using source and random string. More...

bool	generate_pbkdf2 (const std::string &source, const std::string &salt, std::string &digest, unsigned int iterations)
	Transform given password into PKBDF2 digest. More...

Private Attributes
MYSQL_PLUGIN	m_plugin_info
	Plugin handle. More...

std::atomic< size_t >	m_stored_digest_rounds
	Number of rounds for stored digest. More...

std::atomic< Stored_digest_info >	m_stored_digest_type
	Stored digest type. More...

std::atomic_uint	m_fast_digest_rounds
	Number of rounds for fast digest. More...

mysql_rwlock_t	m_cache_lock
	Lock to protect `m_cache`. More...

SHA2_password_cache	m_cache
	user=>password cache More...

std::atomic_bool	m_enforce_storage_format

Friends
class	sha2_password_unittest::SHA256_digestTest

Detailed Description

Class to handle caching_sha2_authentication Provides methods for:

Fast authentication
Strong authentication
Removal of cached entry

Constructor & Destructor Documentation

◆ Caching_sha2_password()

sha2_password::Caching_sha2_password::Caching_sha2_password	(	MYSQL_PLUGIN	plugin_handle,
		size_t	stored_digest_rounds,
		Stored_digest_info	digest_type = `Stored_digest_info::CRYPT5`,
		unsigned int	fast_digest_rounds = `DEFAULT_FAST_DIGEST_ROUNDS`,
		bool	enforce_storage_format = `false`
	)

Caching_sha2_password constructor - Initializes rw lock.

Parameters

[in]	plugin_handle	MYSQL_PLUGIN reference
[in]	stored_digest_rounds	Number of rounds for stored digest generation
[in]	digest_type	SHA2 type to be used
[in]	fast_digest_rounds	Number of rounds for fast digest generation
[in]	enforce_storage_format	Whether storage format is strictly enforced or not

◆ ~Caching_sha2_password()

sha2_password::Caching_sha2_password::~Caching_sha2_password ( )

Caching_sha2_password destructor - destroy rw lock.

Member Function Documentation

◆ authenticate()

std::pair< bool, bool > sha2_password::Caching_sha2_password::authenticate	(	const std::string &	authorization_id,
		const std::string_view *	serialized_string,
		const std::string &	plaintext_password,
		bool &	set_password_expired_flag
	)

Perform slow authentication.

Disect serialized_string and retrieve a. Salt b. Hash iteration count c. Expected hash
Use plaintext password, salt and hash iteration count to generate hash.
Validate generated hash against expected hash.

In case of successful authentication, update password cache.

Parameters

[in]	authorization_id	User information
[in]	serialized_string	Information retrieved from mysql.authentication_string column
[in]	plaintext_password	Password as received from client
[out]	set_password_expired_flag	Whether to suggest server to set password expired flag

Returns: Outcome of comparison against expected hash and whether second password was used or not.

◆ clear_cache()

void sha2_password::Caching_sha2_password::clear_cache ( )

Clear the password cache.

◆ compare_against_stored()

std::pair< bool, bool > sha2_password::Caching_sha2_password::compare_against_stored	(	const std::string &	src,
		const std::string_view &	stored,
		const std::optional< std::string > &	authorization_id,
		Stored_digest_info &	digest_type
	)

◆ deserialize()

bool sha2_password::Caching_sha2_password::deserialize	(	const std::string_view &	serialized_string,
		Stored_digest_info &	digest_type,
		std::string &	salt,
		std::string &	digest,
		size_t &	iterations
	)

Deserialize obtained hash and retrieve various parts.

From stored string, following parts are retrieved: Digest type Salt Iteration count hash

Expected format DELIMITER[digest_type]DELIMITER[iterations]DELIMITER[salt][digest]

digest_type: A => SHA256

iterations: 005 => 5*ITERATION_MULTIPLIER

salt: Random string. Length SALT_LENGTH

digest: SHA2 digest. Length STORED_SHA256_DIGEST_LENGTH

Parameters

[in]	serialized_string	serialized string
[out]	digest_type	Digest algorithm
[out]	salt	Random string used for hashing
[out]	digest	Digest stored
[out]	iterations	Number of hash iterations

Returns: status of parsing

Return values

false.	Success. out variables updated.
true.	Failure. out variables should not be used.

◆ fast_authenticate()

std::pair< bool, bool > sha2_password::Caching_sha2_password::fast_authenticate	(	const std::string &	authorization_id,
		const unsigned char *	random,
		unsigned int	random_length,
		const unsigned char *	scramble,
		bool	check_second
	)

Perform fast authentication.

Retrieve hash from cache
Validate it against received scramble

Parameters

[in]	authorization_id	User information
[in]	random	Per session random number
[in]	random_length	Length of the random number
[in]	scramble	Scramble received from the client
[in]	check_second	Check secondary credentials

Returns: Outcome of scramble validation and whether second password was used or not.

◆ generate_crypt5()

bool sha2_password::Caching_sha2_password::generate_crypt5	(	const std::string &	source,
		const std::string &	salt,
		std::string &	digest,
		unsigned int	iterations
	)

protected

Generate multi-round sha2 hash using source and random string.

This is a wrapper around my_crypt_genhash

Parameters

[in]	source	Source text
[in]	salt	Random text
[out]	digest	Generated sha2 digest
[in]	iterations	Number of hash iterations

Returns: result of hash generation

Return values

false	Success
true	Error

◆ generate_fast_digest()

bool sha2_password::Caching_sha2_password::generate_fast_digest	(	const std::string &	plaintext_password,
		sha2_cache_entry &	digest,
		unsigned int	pos
	)

Generate digest based on get_fast_digest_rounds()

Parameters

[out]	digest	Digest output buffer
[in]	plaintext_password	Source text
[in]	pos	Position of the digest

Returns: status of digest generation

Return values

false	Success.
true	Error. Don't rely on digest.

◆ generate_pbkdf2()

bool sha2_password::Caching_sha2_password::generate_pbkdf2	(	const std::string &	source,
		const std::string &	salt,
		std::string &	digest,
		unsigned int	iterations
	)

protected

Transform given password into PKBDF2 digest.

Parameters

[in]	source	Source text
[in]	salt	Random text
[out]	digest	Generated PBKDF2 digest
[in]	iterations	Number of iterations

Returns: Result of the digest generation

Return values

false	Success
true	Error

◆ generate_stored_digest()

bool sha2_password::Caching_sha2_password::generate_stored_digest	(	const std::string &	src,
		std::string &	serialized_string
	)

◆ get_cache_count()

size_t sha2_password::Caching_sha2_password::get_cache_count ( )

Get cache count.

Returns: number of elements in the cache

◆ get_enforce_storage_format()

bool sha2_password::Caching_sha2_password::get_enforce_storage_format ( )

inline

◆ get_fast_digest_rounds()

unsigned int sha2_password::Caching_sha2_password::get_fast_digest_rounds ( )

inline

◆ get_stored_digest_rounds()

size_t sha2_password::Caching_sha2_password::get_stored_digest_rounds ( )

inline

◆ get_stored_digest_type()

Stored_digest_info sha2_password::Caching_sha2_password::get_stored_digest_type ( ) const

inline

◆ remove_cached_entry()

void sha2_password::Caching_sha2_password::remove_cached_entry ( const std::string & authorization_id )

Remove an entry from the cache.

This can happen due to one of the following: a. DROP USER b. RENAME USER

Parameters

[in] authorization_id User name

◆ serialize()

bool sha2_password::Caching_sha2_password::serialize	(	std::string &	serialized_string,
		const Stored_digest_info &	digest_type,
		const std::string &	salt,
		const std::string &	digest,
		size_t	iterations
	)

Serialize following: a.

Digest type b. Iteration count c. Salt d. Hash Expected output format: DELIMITER[digest_type]DELIMITER[iterations]DELIMITER[salt][digest]

digest_type: A => CRYPT5 B => PBKDF2

iterations: 3 digit hex * 1000 E.g. For 5000 => 005

salt: Random string. Length CRYPT_SALT_LENGTH

digest: SHA2 digest. Length STORED_SHA256_DIGEST_LENGTH

Parameters

[out]	serialized_string	String to be stored
[in]	digest_type	Digest algorithm
[in]	salt	Random string used for hashing
[in]	digest	Generated Digest
[in]	iterations	Number of hash iterations

◆ set_enforce_storage_format()

void sha2_password::Caching_sha2_password::set_enforce_storage_format ( bool value )

inline

◆ set_stored_digest_rounds()

void sha2_password::Caching_sha2_password::set_stored_digest_rounds ( size_t stored_digest_rounds )

inline

◆ set_stored_digest_type()

void sha2_password::Caching_sha2_password::set_stored_digest_type ( Stored_digest_info digest_type )

inline

◆ validate_hash()

bool sha2_password::Caching_sha2_password::validate_hash ( const std::string & serialized_string )

Validate a hash format.

Parameters

[in] serialized_string Supplied hash

Returns: result of validation

Return values

false	Valid hash
true	Invalid hash

Friends And Related Function Documentation

◆ sha2_password_unittest::SHA256_digestTest

friend class sha2_password_unittest::SHA256_digestTest

friend

Member Data Documentation

◆ m_cache

SHA2_password_cache sha2_password::Caching_sha2_password::m_cache

private

user=>password cache

◆ m_cache_lock

mysql_rwlock_t sha2_password::Caching_sha2_password::m_cache_lock

private

Lock to protect m_cache.

◆ m_enforce_storage_format

std::atomic_bool sha2_password::Caching_sha2_password::m_enforce_storage_format

private

◆ m_fast_digest_rounds

std::atomic_uint sha2_password::Caching_sha2_password::m_fast_digest_rounds

private

Number of rounds for fast digest.

◆ m_plugin_info

MYSQL_PLUGIN sha2_password::Caching_sha2_password::m_plugin_info

private

Plugin handle.

◆ m_stored_digest_rounds

std::atomic<size_t> sha2_password::Caching_sha2_password::m_stored_digest_rounds

private

Number of rounds for stored digest.

◆ m_stored_digest_type

std::atomic<Stored_digest_info> sha2_password::Caching_sha2_password::m_stored_digest_type

private

Stored digest type.

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

sql/auth/i_sha2_password.h
sql/auth/sha2_password.cc

Public Member Functions

Protected Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Caching_sha2_password()

◆ ~Caching_sha2_password()

Member Function Documentation

◆ authenticate()

◆ clear_cache()

◆ compare_against_stored()

◆ deserialize()

◆ fast_authenticate()

◆ generate_crypt5()

◆ generate_fast_digest()

◆ generate_pbkdf2()

◆ generate_stored_digest()

◆ get_cache_count()

◆ get_enforce_storage_format()

◆ get_fast_digest_rounds()

◆ get_stored_digest_rounds()

◆ get_stored_digest_type()

◆ remove_cached_entry()

◆ serialize()

◆ set_enforce_storage_format()

◆ set_stored_digest_rounds()

◆ set_stored_digest_type()

◆ validate_hash()

Friends And Related Function Documentation

◆ sha2_password_unittest::SHA256_digestTest

Member Data Documentation

◆ m_cache

◆ m_cache_lock

◆ m_enforce_storage_format

◆ m_fast_digest_rounds

◆ m_plugin_info

◆ m_stored_digest_rounds

◆ m_stored_digest_type