MySQL 8.0.33
Source Code Documentation
plugin_auth.h
Go to the documentation of this file.
1#ifndef MYSQL_PLUGIN_AUTH_INCLUDED
2/* Copyright (c) 2010, 2023, 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 */
142 /**
143 Refers to authentication details of 1st, 2nd or 3rd factor authentication
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*/
173typedef 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 */
187typedef 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*/
203typedef 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*/
217typedef 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 */
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 authentication 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