MySQL 8.3.0
Source Code Documentation
sha2_password::Caching_sha2_password Class Reference

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_handleMYSQL_PLUGIN reference
[in]stored_digest_roundsNumber of rounds for stored digest generation
[in]fast_digest_roundsNumber of rounds for fast digest generation
[in]digest_typeSHA2 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.

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

In case of successful authentication, update password cache.

Parameters
[in]authorization_idUser information
[in]serialized_stringInformation retrieved from mysql.authentication_string column
[in]plaintext_passwordPassword 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_stringserialized string
[out]digest_typeDigest algorithm
[out]saltRandom string used for hashing
[out]digestDigest stored
[out]iterationsNumber 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.

  1. Retrieve hash from cache
  2. Validate it against received scramble
Parameters
[in]authorization_idUser information
[in]randomPer session random number
[in]random_lengthLength of the random number
[in]scrambleScramble received from the client
[in]check_secondCheck 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]digestDigest output buffer
[in]plaintext_passwordSource text
[in]posPosition of the digest
Returns
status of digest generation
Return values
falseSuccess.
trueError. 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]sourceSource text
[in]randomRandom text
[out]digestGenerated sha2 digest
[in]iterationsNumber of hash iterations
Returns
result of password check
Return values
falsePassword matches
truePassword 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_idUser 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_stringString to be stored
[in]digest_typeDigest algorithm
[in]saltRandom string used for hashing
[in]digestGenerated Digest
[in]iterationsNumber 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_stringSupplied hash
Returns
result of validation
Return values
falseValid hash
trueInvalid 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: