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, unsigned int fast_digest_rounds=DEFAULT_FAST_DIGEST_ROUNDS, Digest_info digest_type=Digest_info::SHA256_DIGEST)
	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 *serialized_string, const std::string &plaintext_password)
	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 &serialized_string, 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 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 m_fast_digest_rounds. More...

bool	generate_sha2_multi_hash (const std::string &src, const std::string &random, std::string *digest, unsigned int iterations)
	Generate multi-round sha2 hash using source and random string. More...

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

Digest_info	get_digest_type () const

size_t	get_digest_rounds ()

Private Attributes
MYSQL_PLUGIN	m_plugin_info
	Plugin handle. More...

size_t	m_stored_digest_rounds
	Number of rounds for stored digest. More...

unsigned int	m_fast_digest_rounds
	Number of rounds for fast digest. More...

Digest_info	m_digest_type
	Digest type. More...

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

SHA2_password_cache	m_cache
	user=>password cache More...

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,
		unsigned int	fast_digest_rounds = `DEFAULT_FAST_DIGEST_ROUNDS`,
		Digest_info	digest_type = `Digest_info::SHA256_DIGEST`
	)

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]	fast_digest_rounds	Number of rounds for fast digest generation
[in]	digest_type	SHA2 type to be used

◆ ~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 *	serialized_string,
		const std::string &	plaintext_password
	)

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

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.

◆ deserialize()

bool sha2_password::Caching_sha2_password::deserialize	(	const std::string &	serialized_string,
		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_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 m_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_sha2_multi_hash()

bool sha2_password::Caching_sha2_password::generate_sha2_multi_hash	(	const std::string &	source,
		const std::string &	random,
		std::string *	digest,
		unsigned int	iterations
	)

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

This is a wrapper around my_crypt_genhash

Parameters

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

Returns: result of password check

Return values

false	Password matches
true	Password does not match

◆ get_cache_count()

size_t sha2_password::Caching_sha2_password::get_cache_count ( )

Get cache count.

Returns: number of elements in the cache

◆ get_digest_rounds()

size_t sha2_password::Caching_sha2_password::get_digest_rounds ( )

inline

◆ get_digest_type()

Digest_info sha2_password::Caching_sha2_password::get_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 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 => SHA256

iterations: 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

◆ 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

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_digest_type

Digest_info sha2_password::Caching_sha2_password::m_digest_type

private

Digest type.

◆ m_fast_digest_rounds

unsigned int 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

size_t sha2_password::Caching_sha2_password::m_stored_digest_rounds

private

Number of rounds for stored digest.

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

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Caching_sha2_password()

◆ ~Caching_sha2_password()

Member Function Documentation

◆ authenticate()

◆ clear_cache()

◆ deserialize()

◆ fast_authenticate()

◆ generate_fast_digest()

◆ generate_sha2_multi_hash()

◆ get_cache_count()

◆ get_digest_rounds()

◆ get_digest_type()

◆ remove_cached_entry()

◆ serialize()

◆ validate_hash()

Member Data Documentation

◆ m_cache

◆ m_cache_lock

◆ m_digest_type

◆ m_fast_digest_rounds

◆ m_plugin_info

◆ m_stored_digest_rounds