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