MySQL 9.0.0
Source Code Documentation
authentication_policy.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2023, 2024, Oracle and/or its affiliates.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2.0,
6 as published by the Free Software Foundation.
7
8 This program is designed to work with certain software (including
9 but not limited to OpenSSL) that is licensed under separate terms,
10 as designated in a particular file or component or in included license
11 documentation. The authors of MySQL hereby grant you an additional
12 permission to link the program and your derivative works with the
13 separately licensed software that they have either included with
14 the program or referenced in the documentation.
15
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License, version 2.0, for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, write to the Free Software
23 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24*/
25#ifndef _AUTHENTICATION_POLICY_H_
26#define _AUTHENTICATION_POLICY_H_
27
28#include <string>
29#include <vector>
30
31#include "mysql/plugin_auth.h"
32#include "sql/sql_plugin_ref.h"
33
34/** namespace for authentication policy */
35namespace authentication_policy {
36
37/**
38 Class representing authenticalion policy factor.
39*/
40class Factor {
41 public:
42 /**
43 Constructor.
44
45 @param [in] mandatory_plugin mandatory plugin name
46 @param [in] default_plugin default plugin name
47 */
48 Factor(const std::string &mandatory_plugin,
49 const std::string &default_plugin);
50
51 /**
52 Is the factor optional (may be omitted)?
53
54 @retval true the factor is optional
55 @retval false the factor is not optional
56 */
57 inline bool is_optional() const { return mandatory_plugin.empty(); }
58
59 /**
60 Is the factor whichever (any auth plugin may be used for it)?
61
62 @retval true the factor is whichever
63 @retval false the factor is not whichever
64 */
65 inline bool is_whichever() const { return mandatory_plugin == "*"; }
66
67 /**
68 Has the factor a concrete mandatory auth plugin specified?
69
70 @retval true the factor has a mandatory plugin
71 @retval false the factor doesn't have a mandatory plugin
72 */
73 inline bool is_mandatory_specified() const {
74 return !is_optional() && !is_whichever();
75 }
76
77 /**
78 Has the factor a default plugin specified?
79
80 @retval true the factor has a default plugin
81 @retval false the factor doesn't have a default plugin
82 */
83 inline bool is_default_specified() const { return !default_plugin.empty(); }
84
85 /**
86 Get mandatory plugin name.
87
88 @return reference to the plugin name.
89 */
90 const std::string &get_mandatory_plugin() const { return mandatory_plugin; }
91
92 /**
93 Get default plugin name.
94
95 @return reference to the plugin name.
96 */
97 const std::string &get_default_plugin() const { return default_plugin; }
98
99 /**
100 Get mandatory plugin name (if defined) else the default plugin name.
101 This is used e.g. while creating user when the statement doesn't provide
102 plugin name for nth factor.
103
104 @return reference to the plugin name.
105 */
106 const std::string &get_mandatory_or_default_plugin() const {
108 }
109
110 protected:
111 /**
112 Set default to system defined. It is used for 1. factor to avoid undefined
113 default authentication.
114 */
115 void set_default() { default_plugin = "caching_sha2_password"; }
116
117 private:
118 /**
119 If empty: the factor is optional
120 If "*" : the factor may be whichever plugin
121 Else : mandatory plugin name
122 */
123 std::string mandatory_plugin;
124 /**
125 Default plugin name
126 */
127 std::string default_plugin;
128
129 friend class Policy;
130};
131
132/**
133 Type of container with authentication policy factors.
134*/
135using Factors = std::vector<Factor>;
136
137/**
138 Class representing authentication policy.
139*/
140class Policy {
141 protected:
142 /** Pointer to the authentication policy object */
143 static Policy *policy;
144
145 /** Destructor */
147
148 /**
149 Validate @@authentication_policy variable value.
150
151 @param [in] new_policy the new value of the variable.
152
153 @retval false success
154 @retval true failure
155 */
156 bool validate(const char *new_policy);
157
158 /**
159 Update @@authentication_policy variable value.
160
161 @param [in] new_policy the new value of the variable.
162
163 @retval false success
164 @retval true failure
165 */
166 bool update(const char *new_policy);
167
168 /**
169 Get copy of the authentication policy factors.
170 The aim is to work is with consistent snapshot of the factor avoiding long
171 time locking.
172
173 @param factors [out] authentication policy factors
174 */
175 void get_factors(Factors &factors) const;
176
177 /**
178 Get copy of default plugin name.
179
180 @param factor [in] no of the factor
181 @param name [out] copy of the name
182 */
183 void get_default_plugin(size_t factor, std::string &name) const;
184
185 /**
186 Get copy of default plugin name.
187
188 @param factor [in] no of the factor
189 @param mem_root [in] place to allocate the name
190 @param name [out] copy of the name
191 */
192 void get_default_plugin(size_t factor, MEM_ROOT *mem_root,
193 LEX_CSTRING *name) const;
194
195 /**
196 Parse @@authentication_policy variable value.
197
198 Format of the variable:
199 authentication_policy = factor_spec[, factor_spec] ...
200 factor_spec = [ * | <empty> | mandatory_plugin |
201 *:default_plugin ]
202
203 Additional rules:
204 The first plugin cannot be empty (optional)
205 An empty (optional) plugin can be followed only by empty (optional) plugins.
206 The number of factors is limited to 3.
207
208 Below are some invalid values:
209 ',,'
210 ',authentication_fido,'
211 ',:caching_sha2_password'
212 'caching_sha2_password,,authentication_fido'
213 'caching_sha2_password,:authentication_ldap_simple,authentication_fido'
214 ',authentication_fido,authentication_ldap_simple'
215 ',*:authentication_fido,'
216 'caching_sha2_password:authentication_ldap_simple'
217
218 @param new_policy_value [in] new value of the variable
219 @param parsed_factors [out] parsed factors
220
221 @retval false OK
222 @retval true Error
223 */
224 static bool parse(const std::string &new_policy_value,
225 Factors &parsed_factors);
226
227 private:
228 /** Actual authentication policy factors. */
230 /**
231 Verified, but not yet set authentication policy factors.
232 Set in validate(), replace actual factors in update().
233 Used to avoid second validation in update().
234 */
236 /**
237 The verified policy value. Used to ensure the following validate() and
238 update() work with the same value.
239 */
241 /*
242 Container with server authentication plugin descriptors. Each descriptor is
243 locked and stored in plugin_refs while validating a new policy and unlocked
244 after update. This ensures that no plugin unloaded in between check()
245 and update() of authentication_policy variable.
246 */
247 std::vector<plugin_ref> plugin_refs;
248
249 /**
250 Release all plugin references and clear plugin_refs container.
251 */
252 inline void release_plugin_refs() {
253 for (auto plugin : plugin_refs) plugin_unlock(nullptr, plugin);
254 plugin_refs.clear();
255 }
256
257 /**
258 Get server authentication plugin descriptor by plugin name.
259 Store the descriptor in plugin_refs.
260
261 @param plugin_name [in] name of the plugin
262 @return server authentication plugin descriptor
263 */
264 st_mysql_auth *get_mysql_auth(const std::string &plugin_name);
265
266 friend bool policy_validate(const char *new_policy);
267 friend inline bool policy_update(const char *new_policy);
268 friend void get_policy_factors(Factors &factors);
269 friend void get_first_factor_default_plugin(std::string &name);
272 friend int init(const char *opt_authentication_policy);
273 friend void deinit();
274};
275
276/**
277 Initialize authentication policy
278
279 @param opt_authentication_policy [in] value of authentication_policy sysvar
280
281 @retval 0 success
282 @retval non 0 failure;
283*/
284int init(const char *opt_authentication_policy);
285
286/**
287 Deinitialize authentication policy
288*/
289void deinit();
290
291/**
292 Validate @@authentication_policy variable value.
293
294 @param [in] new_policy the new value of the variable.
295
296 @retval false success
297 @retval true failure
298*/
299inline bool policy_validate(const char *new_policy) {
300 assert(Policy::policy);
301 return Policy::policy->validate(new_policy);
302}
303
304/**
305 Validate @@authentication_policy variable value.
306
307 @param [in] new_policy the new value of the variable.
308
309 @retval false success
310 @retval true failure
311*/
312inline bool policy_update(const char *new_policy) {
313 assert(Policy::policy);
314 return Policy::policy->update(new_policy);
315}
316
317/**
318 Get copy of the authentication policy factors.
319 The aim is to work is with consistent snapshot of the factor avoiding long
320 time locking.
321
322 @param factors [out] authentication policy factors
323*/
324inline void get_policy_factors(Factors &factors) {
325 assert(Policy::policy);
326 Policy::policy->get_factors(factors);
327}
328
329/**
330 Get copy of first factor default plugin name.
331
332 @param name [out] copy of the name
333*/
334inline void get_first_factor_default_plugin(std::string &name) {
335 assert(Policy::policy);
337}
338
339/**
340 Get copy of default plugin name.
341
342 @param mem_root [in] place to allocate the name
343 @param name [out] copy of the name
344*/
346 LEX_CSTRING *name) {
347 assert(Policy::policy);
349}
350
351} // namespace authentication_policy
352
353#endif //_AUTHENTICATION_POLICY_H_
Class representing authenticalion policy factor.
Definition: authentication_policy.h:40
bool is_optional() const
Is the factor optional (may be omitted)?
Definition: authentication_policy.h:57
const std::string & get_default_plugin() const
Get default plugin name.
Definition: authentication_policy.h:97
bool is_default_specified() const
Has the factor a default plugin specified?
Definition: authentication_policy.h:83
std::string default_plugin
Default plugin name.
Definition: authentication_policy.h:127
const std::string & get_mandatory_or_default_plugin() const
Get mandatory plugin name (if defined) else the default plugin name.
Definition: authentication_policy.h:106
std::string mandatory_plugin
If empty: the factor is optional If "*" : the factor may be whichever plugin Else : mandatory plugin ...
Definition: authentication_policy.h:123
const std::string & get_mandatory_plugin() const
Get mandatory plugin name.
Definition: authentication_policy.h:90
bool is_mandatory_specified() const
Has the factor a concrete mandatory auth plugin specified?
Definition: authentication_policy.h:73
Factor(const std::string &mandatory_plugin, const std::string &default_plugin)
Constructor.
Definition: authentication_policy.cc:53
bool is_whichever() const
Is the factor whichever (any auth plugin may be used for it)?
Definition: authentication_policy.h:65
void set_default()
Set default to system defined.
Definition: authentication_policy.h:115
Class representing authentication policy.
Definition: authentication_policy.h:140
static Policy * policy
Pointer to the authentication policy object.
Definition: authentication_policy.h:143
~Policy()
Destructor.
Definition: authentication_policy.h:146
Factors new_factors
Verified, but not yet set authentication policy factors.
Definition: authentication_policy.h:235
Factors factors
Actual authentication policy factors.
Definition: authentication_policy.h:229
friend bool policy_update(const char *new_policy)
Validate @authentication_policy variable value.
Definition: authentication_policy.h:312
st_mysql_auth * get_mysql_auth(const std::string &plugin_name)
Get server authentication plugin descriptor by plugin name.
Definition: authentication_policy.cc:57
friend bool policy_validate(const char *new_policy)
Validate @authentication_policy variable value.
Definition: authentication_policy.h:299
void release_plugin_refs()
Release all plugin references and clear plugin_refs container.
Definition: authentication_policy.h:252
friend void get_first_factor_default_plugin(std::string &name)
Get copy of first factor default plugin name.
Definition: authentication_policy.h:334
void get_default_plugin(size_t factor, std::string &name) const
Get copy of default plugin name.
Definition: authentication_policy.cc:221
friend int init(const char *opt_authentication_policy)
Initialize authentication policy.
Definition: authentication_policy.cc:237
std::vector< plugin_ref > plugin_refs
Definition: authentication_policy.h:247
friend void deinit()
Component deinitialization.
Definition: audit_api_message_emit.cc:580
static bool parse(const std::string &new_policy_value, Factors &parsed_factors)
Parse @authentication_policy variable value.
Definition: authentication_policy.cc:67
bool update(const char *new_policy)
Update @authentication_policy variable value.
Definition: authentication_policy.cc:196
std::string verified_policy_value
The verified policy value.
Definition: authentication_policy.h:240
bool validate(const char *new_policy)
Validate @authentication_policy variable value.
Definition: authentication_policy.cc:134
friend void get_policy_factors(Factors &factors)
Get copy of the authentication policy factors.
Definition: authentication_policy.h:324
void get_factors(Factors &factors) const
Get copy of the authentication policy factors.
Definition: authentication_policy.cc:215
static MEM_ROOT mem_root
Definition: client_plugin.cc:114
char * opt_authentication_policy
Definition: mysqld.cc:1511
namespace for authentication policy
Definition: authentication_policy.cc:44
int init(const char *opt_authentication_policy)
Initialize authentication policy.
Definition: authentication_policy.cc:237
bool policy_validate(const char *new_policy)
Validate @authentication_policy variable value.
Definition: authentication_policy.h:299
std::vector< Factor > Factors
Type of container with authentication policy factors.
Definition: authentication_policy.h:135
bool policy_update(const char *new_policy)
Validate @authentication_policy variable value.
Definition: authentication_policy.h:312
void deinit()
Deinitialize authentication policy.
Definition: authentication_policy.cc:255
void get_policy_factors(Factors &factors)
Get copy of the authentication policy factors.
Definition: authentication_policy.h:324
void get_first_factor_default_plugin(std::string &name)
Get copy of first factor default plugin name.
Definition: authentication_policy.h:334
Authentication Plugin API.
void plugin_unlock(THD *thd, plugin_ref plugin)
Definition: sql_plugin.cc:1261
LEX_CSTRING * plugin_name(st_plugin_int **ref)
Definition: sql_plugin_ref.h:95
case opt name
Definition: sslopt-case.h:29
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:83
Definition: mysql_lex_string.h:40
Server authentication plugin descriptor.
Definition: plugin_auth.h:227