MySQL 8.1.0
Source Code Documentation
i_sha2_password.h
Go to the documentation of this file.
1/*
2Copyright (c) 2017, 2023, Oracle and/or its affiliates.
3
4This program is free software; you can redistribute it and/or modify
5it under the terms of the GNU General Public License, version 2.0,
6as published by the Free Software Foundation.
7
8This program is also distributed with certain software (including
9but not limited to OpenSSL) that is licensed under separate terms,
10as designated in a particular file or component or in included license
11documentation. The authors of MySQL hereby grant you an additional
12permission to link the program and your derivative works with the
13separately licensed software that they have included with MySQL.
14
15This program is distributed in the hope that it will be useful,
16but WITHOUT ANY WARRANTY; without even the implied warranty of
17MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18GNU General Public License, version 2.0, for more details.
19
20You should have received a copy of the GNU General Public License
21along with this program; if not, write to the Free Software
22Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef I_SHA2_PASSWORD_INCLUDED
25#define I_SHA2_PASSWORD_INCLUDED
26
27#include <string>
28#include <unordered_map>
29
30#include "crypt_genhash_impl.h" /* For salt, sha2 digest */
31#include "mysql/plugin.h" /* MYSQL_PLUGIN */
32#include "mysql/psi/mysql_rwlock.h" /* mysql_rwlock_t */
34
35/**
36 @file sql/auth/i_sha2_password.h
37 Classes for caching_sha2_authentication plugin
38*/
39
40/**
41 @defgroup auth_caching_sha2_auth caching_sha2_authentication information
42 @{
43*/
44namespace sha2_password {
45/* fast digest rounds */
46const unsigned int MIN_FAST_DIGEST_ROUNDS = 2;
47const unsigned int DEFAULT_FAST_DIGEST_ROUNDS = 2;
48const unsigned int MAX_FAST_DIGEST_ROUNDS = 1000;
49
50/* Length of Digest Info field */
51const unsigned int DIGEST_INFO_LENGTH = 1;
52/* Length of iteration info field */
53const unsigned int ITERATION_LENGTH = 3;
54/* Iteration multiplier to be used on extracted iteration count */
55const unsigned int ITERATION_MULTIPLIER = 1000;
56/* Upper cap on iterations */
57const long unsigned int MAX_ITERATIONS = 0xFFF * ITERATION_MULTIPLIER;
58/* length of salt */
59const unsigned int SALT_LENGTH = CRYPT_SALT_LENGTH;
60/* $ + A + $ + ITERATION_LENGTH + $ + SALT_LENGTH + CACHING_SHA2_DIGEST_LENGTH =
61 * 59 */
62const unsigned int SHA256_AUTH_STRING_LEN =
64/* Delimiter character */
65const char DELIMITER = '$';
66/* Store digest length */
67const unsigned int STORED_SHA256_DIGEST_LENGTH = 43;
68/* stored digest rounds*/
72/* Maximum password length */
74/* Maximum supported passwords */
75const unsigned int MAX_PASSWORDS = 2;
76
77typedef struct sha2_cache_entry {
80
81/**
82 Password cache used for caching_sha2_authentication
83*/
84
86 public:
87 typedef std::unordered_map<std::string, sha2_cache_entry> password_cache;
88
91 bool add(const std::string authorization_id,
92 const sha2_cache_entry &entry_to_be_cached);
93 bool remove(const std::string authorization_id);
94 bool search(const std::string authorization_id,
95 sha2_cache_entry &cache_entry);
96 /** Returns number of cache entries present */
97 size_t size() { return m_password_cache.size(); }
98 void clear_cache();
99
100 private:
102};
103
104/**
105 Class to handle caching_sha2_authentication
106 Provides methods for:
107 - Fast authentication
108 - Strong authentication
109 - Removal of cached entry
110*/
112 public:
114 MYSQL_PLUGIN plugin_handle, size_t stored_digest_rounds,
115 unsigned int fast_digest_rounds = DEFAULT_FAST_DIGEST_ROUNDS,
118 std::pair<bool, bool> authenticate(const std::string &authorization_id,
119 const std::string *serialized_string,
120 const std::string &plaintext_password);
121 std::pair<bool, bool> fast_authenticate(const std::string &authorization_id,
122 const unsigned char *random,
123 unsigned int random_length,
124 const unsigned char *scramble,
125 bool check_second);
126 void remove_cached_entry(const std::string authorization_id);
127 bool deserialize(const std::string &serialized_string,
128 Digest_info &digest_type, std::string &salt,
129 std::string &digest, size_t &iterations);
130 bool serialize(std::string &serialized_string, const Digest_info &digest_type,
131 const std::string &salt, const std::string &digest,
132 size_t iterations);
133 bool generate_fast_digest(const std::string &plaintext_password,
134 sha2_cache_entry &digest, unsigned int loc);
135 bool generate_sha2_multi_hash(const std::string &src,
136 const std::string &random, std::string *digest,
137 unsigned int iterations);
138 size_t get_cache_count();
139 void clear_cache();
140 bool validate_hash(const std::string serialized_string);
143
144 private:
145 /** Plugin handle */
147 /** Number of rounds for stored digest */
149 /** Number of rounds for fast digest */
151 /** Digest type */
153 /** Lock to protect @c m_cache */
155 /** user=>password cache */
157};
158} // namespace sha2_password
159
160/** @} (end of auth_caching_sha2_auth) */
161
162#endif // !I_SHA2_PASSWORD_INCLUDED
Class to handle caching_sha2_authentication Provides methods for:
Definition: i_sha2_password.h:111
size_t get_cache_count()
Get cache count.
Definition: sha2_password.cc:687
SHA2_password_cache m_cache
user=>password cache
Definition: i_sha2_password.h:156
std::pair< bool, bool > authenticate(const std::string &authorization_id, const std::string *serialized_string, const std::string &plaintext_password)
Perform slow authentication.
Definition: sha2_password.cc:235
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.
Definition: sha2_password.cc:350
Digest_info get_digest_type() const
Definition: i_sha2_password.h:141
unsigned int m_fast_digest_rounds
Number of rounds for fast digest.
Definition: i_sha2_password.h:150
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.
Definition: sha2_password.cc:439
size_t get_digest_rounds()
Definition: i_sha2_password.h:142
mysql_rwlock_t m_cache_lock
Lock to protect m_cache.
Definition: i_sha2_password.h:154
void clear_cache()
Clear the password cache.
Definition: sha2_password.cc:694
size_t m_stored_digest_rounds
Number of rounds for stored digest.
Definition: i_sha2_password.h:148
bool generate_fast_digest(const std::string &plaintext_password, sha2_cache_entry &digest, unsigned int loc)
Generate digest based on m_fast_digest_rounds.
Definition: sha2_password.cc:600
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.
Definition: sha2_password.cc:649
Digest_info m_digest_type
Digest type.
Definition: i_sha2_password.h:152
void remove_cached_entry(const std::string authorization_id)
Remove an entry from the cache.
Definition: sha2_password.cc:397
~Caching_sha2_password()
Caching_sha2_password destructor - destroy rw lock.
Definition: sha2_password.cc:209
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.
Definition: sha2_password.cc:540
bool validate_hash(const std::string serialized_string)
Validate a hash format.
Definition: sha2_password.cc:709
MYSQL_PLUGIN m_plugin_info
Plugin handle.
Definition: i_sha2_password.h:146
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.
Definition: sha2_password.cc:185
Password cache used for caching_sha2_authentication.
Definition: i_sha2_password.h:85
password_cache m_password_cache
Definition: i_sha2_password.h:101
~SHA2_password_cache()
Destructor - Release all memory.
Definition: sha2_password.cc:88
size_t size()
Returns number of cache entries present
Definition: i_sha2_password.h:97
void clear_cache()
Clear the cache - Release all memory.
Definition: sha2_password.cc:165
bool add(const std::string authorization_id, const sha2_cache_entry &entry_to_be_cached)
Add an entry in cache We manage our own memory.
Definition: sha2_password.cc:106
bool remove(const std::string authorization_id)
Remove an entry from the cache.
Definition: sha2_password.cc:126
bool search(const std::string authorization_id, sha2_cache_entry &cache_entry)
Search an entry from the cache.
Definition: sha2_password.cc:149
std::unordered_map< std::string, sha2_cache_entry > password_cache
Definition: i_sha2_password.h:87
#define MAX_PLAINTEXT_LENGTH
Definition: crypt_genhash_impl.h:40
#define CRYPT_SALT_LENGTH
Definition: crypt_genhash_impl.h:33
#define ROUNDS_DEFAULT
Definition: crypt_genhash_impl.h:29
#define ROUNDS_MIN
Definition: crypt_genhash_impl.h:30
#define ROUNDS_MAX
Definition: crypt_genhash_impl.h:31
Classes for caching_sha2_authentication plugin.
void * MYSQL_PLUGIN
Definition: plugin.h:81
void scramble(char *to, const char *message, const char *password)
Produce an obscure octet sequence from password and random string, received from the server.
Definition: password.cc:270
static unsigned int iterations
Definition: mysqlslap.cc:188
Definition: i_sha2_password.h:44
const unsigned int DIGEST_INFO_LENGTH
Definition: i_sha2_password.h:51
const unsigned int CACHING_SHA2_DIGEST_LENGTH
Definition: i_sha2_password_common.h:44
const char DELIMITER
Definition: i_sha2_password.h:65
const unsigned int STORED_SHA256_DIGEST_LENGTH
Definition: i_sha2_password.h:67
Digest_info
Supported digest information.
Definition: i_sha2_password_common.h:50
const unsigned int ITERATION_LENGTH
Definition: i_sha2_password.h:53
const long unsigned int MAX_ITERATIONS
Definition: i_sha2_password.h:57
const size_t CACHING_SHA2_PASSWORD_MAX_PASSWORD_LENGTH
Definition: i_sha2_password.h:73
const unsigned int MAX_FAST_DIGEST_ROUNDS
Definition: i_sha2_password.h:48
struct sha2_password::sha2_cache_entry sha2_cache_entry
const unsigned int DEFAULT_FAST_DIGEST_ROUNDS
Definition: i_sha2_password.h:47
const size_t MAX_STORED_DIGEST_ROUNDS
Definition: i_sha2_password.h:71
const size_t DEFAULT_STORED_DIGEST_ROUNDS
Definition: i_sha2_password.h:70
const unsigned int MIN_FAST_DIGEST_ROUNDS
Definition: i_sha2_password.h:46
const unsigned int MAX_PASSWORDS
Definition: i_sha2_password.h:75
const unsigned int SHA256_AUTH_STRING_LEN
Definition: i_sha2_password.h:62
const size_t MIN_STORED_DIGEST_ROUNDS
Definition: i_sha2_password.h:69
const unsigned int ITERATION_MULTIPLIER
Definition: i_sha2_password.h:55
const unsigned int SALT_LENGTH
Definition: i_sha2_password.h:59
Instrumentation helpers for rwlock.
An instrumented rwlock structure.
Definition: mysql_rwlock_bits.h:50
Definition: i_sha2_password.h:77
unsigned char digest_buffer[MAX_PASSWORDS][CACHING_SHA2_DIGEST_LENGTH]
Definition: i_sha2_password.h:78