MySQL  8.0.27
Source Code Documentation
plugin_auth.h
Go to the documentation of this file.
1 #ifndef MYSQL_PLUGIN_AUTH_INCLUDED
2 /* Copyright (c) 2010, 2021, 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 also distributed 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 included with MySQL.
14 
15  This program is distributed in the hope that it will be useful,
16  but WITHOUT ANY WARRANTY; without even the implied warranty of
17  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  GNU General Public License, version 2.0, for more details.
19 
20  You should have received a copy of the GNU General Public License
21  along with this program; if not, write to the Free Software
22  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23 
24 /**
25  @file include/mysql/plugin_auth.h
26 
27  Authentication Plugin API.
28 
29  This file defines the API for server authentication plugins.
30 */
31 
32 #define MYSQL_PLUGIN_AUTH_INCLUDED
33 
34 #include <mysql/plugin.h>
35 
36 #define MYSQL_AUTHENTICATION_INTERFACE_VERSION 0x0201
37 
38 #include "plugin_auth_common.h"
39 
40 /* defines for MYSQL_SERVER_AUTH_INFO.password_used */
41 
42 #define PASSWORD_USED_NO 0
43 #define PASSWORD_USED_YES 1
44 #define PASSWORD_USED_NO_MENTION 2
45 
46 /* Authentication flags */
47 
48 #define AUTH_FLAG_PRIVILEGED_USER_FOR_PASSWORD_CHANGE (1L << 0)
49 #define AUTH_FLAG_USES_INTERNAL_STORAGE (1L << 1)
50 #define AUTH_FLAG_REQUIRES_REGISTRATION (1L << 2)
51 
53  /**
54  authentication string for 1st, 2nd and 3rd factor auth plugins
55  */
56  const char *auth_string;
57  /**
58  Length of authentication string for 1st, 2nd and 3rd factor auth plugins
59  */
60  unsigned long auth_string_length;
61  /**
62  Flag which tells if connecting user has performed registration or not.
63  */
65 };
66 
67 /**
68  Provides server plugin access to authentication information
69 */
71  /**
72  User name as sent by the client and shown in USER().
73  NULL if the client packet with the user name was not received yet.
74  */
75  char *user_name;
76 
77  /**
78  Length of user_name
79  */
80  unsigned int user_name_length;
81 
82  /**
83  Refers to multi_factor_auth_info based on which factor is being
84  authenticated.
85  */
86  const char *auth_string;
87 
88  /**
89  Length of auth_string
90  */
91  unsigned long auth_string_length;
92 
93  /**
94  Matching account name as found in the mysql.user table.
95  A plugin can override it with another name that will be
96  used by MySQL for authorization, and shown in CURRENT_USER()
97  */
99 
100  /**
101  The unique user name that was used by the plugin to authenticate.
102  Plugins should put null-terminated UTF-8 here.
103  Available through the @@EXTERNAL_USER variable.
104  */
105  char external_user[512];
106 
107  /**
108  This only affects the "Authentication failed. Password used: %s"
109  error message. has the following values :
110  0 : %s will be NO.
111  1 : %s will be YES.
112  2 : there will be no %s.
113  Set it as appropriate or ignore at will.
114  */
116 
117  /**
118  Set to the name of the connected client host, if it can be resolved,
119  or to its IP address otherwise.
120  */
121  const char *host_or_ip;
122 
123  /**
124  Length of host_or_ip
125  */
126  unsigned int host_or_ip_length;
127 
128  /**
129  Additional password
130  */
132 
133  /**
134  Length of additional password
135  */
137 
138  /**
139  Refers to which factor auth_string to consider during authentication.
140  */
141  unsigned int current_auth_factor;
142  /**
143  Refers to authentication details of 1st, 2nd or 3rd factor authentiction
144  method
145  */
147 };
148 
149 /**
150  Function provided by the plugin which should perform authentication (using
151  the vio functions if necessary) and return 0 if successful. The plugin can
152  also fill the info.authenticated_as field if a different username should be
153  used for authorization.
154 */
157 
158 /**
159  New plugin API to generate password digest out of authentication string.
160  This function will first invoke a service to check for validity of the
161  password based on the policies defined and then generate encrypted hash
162 
163  @param[out] outbuf A buffer provided by server which will hold the
164  authentication string generated by plugin.
165  @param[in,out] outbuflen Length of server provided buffer as IN param and
166  length of plugin generated string as OUT param.
167  @param[in] inbuf auth string provided by user.
168  @param[in] inbuflen auth string length.
169 
170  @retval 0 OK
171  @retval 1 ERROR
172 */
173 typedef int (*generate_authentication_string_t)(char *outbuf,
174  unsigned int *outbuflen,
175  const char *inbuf,
176  unsigned int inbuflen);
177 
178 /**
179  Plugin API to validate password digest.
180 
181  @param[in] inbuf hash string to be validated.
182  @param[in] buflen hash string length.
183 
184  @retval 0 OK
185  @retval 1 ERROR
186  */
187 typedef int (*validate_authentication_string_t)(char *const inbuf,
188  unsigned int buflen);
189 
190 /**
191  Plugin API to convert scrambled password to binary form
192  based on scramble type.
193 
194  @param[in] password The password hash containing the salt.
195  @param[in] password_len The length of the password hash.
196  @param[in,out] salt Used as password hash based on the
197  authentication plugin.
198  @param[in,out] salt_len The length of salt.
199 
200  @retval 0 OK
201  @retval 1 ERROR
202 */
203 typedef int (*set_salt_t)(const char *password, unsigned int password_len,
204  unsigned char *salt, unsigned char *salt_len);
205 
206 /**
207  Plugin API to compare a clear text password with a stored hash
208 
209  @arg hash pointer to the hashed data
210  @arg hash_length length of the hashed data
211  @arg cleartext pointer to the clear text password
212  @arg cleartext_length length of the cleat text password
213  @arg[out] is_error non-zero in case of error extracting the salt
214  @retval 0 the hash was created with that password
215  @retval non-zero the hash was created with a different password
216 */
217 typedef int (*compare_password_with_hash_t)(const char *hash,
218  unsigned long hash_length,
219  const char *cleartext,
220  unsigned long cleartext_length,
221  int *is_error);
222 
223 /**
224  Server authentication plugin descriptor
225 */
227  int interface_version; /** version plugin uses */
228  /**
229  A plugin that a client must use for authentication with this server
230  plugin. Can be NULL to mean "any plugin".
231  */
232  const char *client_auth_plugin;
233 
238 
239  /**
240  Authentication plugin capabilities
241  */
242  const unsigned long authentication_flags;
243 
245 };
246 #endif
static char * password
Definition: mysql_secure_installation.cc:55
Log info(cout, "NOTE")
int(* generate_authentication_string_t)(char *outbuf, unsigned int *outbuflen, const char *inbuf, unsigned int inbuflen)
New plugin API to generate password digest out of authentication string.
Definition: plugin_auth.h:173
int(* authenticate_user_t)(MYSQL_PLUGIN_VIO *vio, MYSQL_SERVER_AUTH_INFO *info)
Function provided by the plugin which should perform authentication (using the vio functions if neces...
Definition: plugin_auth.h:155
int(* validate_authentication_string_t)(char *const inbuf, unsigned int buflen)
Plugin API to validate password digest.
Definition: plugin_auth.h:187
int(* set_salt_t)(const char *password, unsigned int password_len, unsigned char *salt, unsigned char *salt_len)
Plugin API to convert scrambled password to binary form based on scramble type.
Definition: plugin_auth.h:203
int(* compare_password_with_hash_t)(const char *hash, unsigned long hash_length, const char *cleartext, unsigned long cleartext_length, int *is_error)
Plugin API to compare a clear text password with a stored hash.
Definition: plugin_auth.h:217
This file defines constants and data structures that are the same for both client- and server-side au...
#define MYSQL_USERNAME_LENGTH
the max allowed length for a user name
Definition: plugin_auth_common.h:38
Provides plugin access to communication channel.
Definition: plugin_auth_common.h:145
Provides server plugin access to authentication information.
Definition: plugin_auth.h:70
unsigned int user_name_length
Length of user_name.
Definition: plugin_auth.h:80
char * user_name
User name as sent by the client and shown in USER().
Definition: plugin_auth.h:75
int password_used
This only affects the "Authentication failed. Password used: %s" error message.
Definition: plugin_auth.h:115
const char * host_or_ip
Set to the name of the connected client host, if it can be resolved, or to its IP address otherwise.
Definition: plugin_auth.h:121
unsigned long auth_string_length
Length of auth_string.
Definition: plugin_auth.h:91
char external_user[512]
The unique user name that was used by the plugin to authenticate.
Definition: plugin_auth.h:105
unsigned int host_or_ip_length
Length of host_or_ip.
Definition: plugin_auth.h:126
auth_factor_desc * multi_factor_auth_info
Refers to authentication details of 1st, 2nd or 3rd factor authentiction method.
Definition: plugin_auth.h:146
char authenticated_as[MYSQL_USERNAME_LENGTH+1]
Matching account name as found in the mysql.user table.
Definition: plugin_auth.h:98
unsigned long additional_auth_string_length
Length of additional password.
Definition: plugin_auth.h:136
unsigned int current_auth_factor
Refers to which factor auth_string to consider during authentication.
Definition: plugin_auth.h:141
const char * additional_auth_string
Additional password.
Definition: plugin_auth.h:131
const char * auth_string
Refers to multi_factor_auth_info based on which factor is being authenticated.
Definition: plugin_auth.h:86
Definition: plugin_auth.h:52
const char * auth_string
authentication string for 1st, 2nd and 3rd factor auth plugins
Definition: plugin_auth.h:56
unsigned int is_registration_required
Flag which tells if connecting user has performed registration or not.
Definition: plugin_auth.h:64
unsigned long auth_string_length
Length of authentication string for 1st, 2nd and 3rd factor auth plugins.
Definition: plugin_auth.h:60
Server authentication plugin descriptor.
Definition: plugin_auth.h:226
compare_password_with_hash_t compare_password_with_hash
Definition: plugin_auth.h:244
const char * client_auth_plugin
version plugin uses
Definition: plugin_auth.h:232
int interface_version
Definition: plugin_auth.h:227
set_salt_t set_salt
Definition: plugin_auth.h:237
authenticate_user_t authenticate_user
Definition: plugin_auth.h:234
const unsigned long authentication_flags
Authentication plugin capabilities.
Definition: plugin_auth.h:242
generate_authentication_string_t generate_authentication_string
Definition: plugin_auth.h:235
validate_authentication_string_t validate_authentication_string
Definition: plugin_auth.h:236