MySQL  8.0.17
Source Code Documentation
plugin_auth.h
Go to the documentation of this file.
1 #ifndef MYSQL_PLUGIN_AUTH_INCLUDED
2 /* Copyright (c) 2010, 2019, Oracle and/or its affiliates. All rights reserved.
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 0x0200
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 
51 /**
52  Provides server plugin access to authentication information
53 */
55  /**
56  User name as sent by the client and shown in USER().
57  NULL if the client packet with the user name was not received yet.
58  */
59  char *user_name;
60 
61  /**
62  Length of user_name
63  */
64  unsigned int user_name_length;
65 
66  /**
67  A corresponding column value from the mysql.user table for the
68  matching account name
69  */
70  const char *auth_string;
71 
72  /**
73  Length of auth_string
74  */
75  unsigned long auth_string_length;
76 
77  /**
78  Matching account name as found in the mysql.user table.
79  A plugin can override it with another name that will be
80  used by MySQL for authorization, and shown in CURRENT_USER()
81  */
83 
84  /**
85  The unique user name that was used by the plugin to authenticate.
86  Plugins should put null-terminated UTF-8 here.
87  Available through the @@EXTERNAL_USER variable.
88  */
89  char external_user[512];
90 
91  /**
92  This only affects the "Authentication failed. Password used: %s"
93  error message. has the following values :
94  0 : %s will be NO.
95  1 : %s will be YES.
96  2 : there will be no %s.
97  Set it as appropriate or ignore at will.
98  */
100 
101  /**
102  Set to the name of the connected client host, if it can be resolved,
103  or to its IP address otherwise.
104  */
105  const char *host_or_ip;
106 
107  /**
108  Length of host_or_ip
109  */
110  unsigned int host_or_ip_length;
111 
112  /**
113  Additional password
114  */
116 
117  /**
118  Length of additional password
119  */
121 };
122 
123 /**
124  Function provided by the plugin which should perform authentication (using
125  the vio functions if necessary) and return 0 if successful. The plugin can
126  also fill the info.authenticated_as field if a different username should be
127  used for authorization.
128 */
131 
132 /**
133  New plugin API to generate password digest out of authentication string.
134  This function will first invoke a service to check for validity of the
135  password based on the policies defined and then generate encrypted hash
136 
137  @param[out] outbuf A buffer provided by server which will hold the
138  authentication string generated by plugin.
139  @param[in,out] outbuflen Length of server provided buffer as IN param and
140  length of plugin generated string as OUT param.
141  @param[in] inbuf auth string provided by user.
142  @param[in] inbuflen auth string length.
143 
144  @retval 0 OK
145  @retval 1 ERROR
146 */
147 typedef int (*generate_authentication_string_t)(char *outbuf,
148  unsigned int *outbuflen,
149  const char *inbuf,
150  unsigned int inbuflen);
151 
152 /**
153  Plugin API to validate password digest.
154 
155  @param[in] inbuf hash string to be validated.
156  @param[in] buflen hash string length.
157 
158  @retval 0 OK
159  @retval 1 ERROR
160  */
161 typedef int (*validate_authentication_string_t)(char *const inbuf,
162  unsigned int buflen);
163 
164 /**
165  Plugin API to convert scrambled password to binary form
166  based on scramble type.
167 
168  @param[in] password The password hash containing the salt.
169  @param[in] password_len The length of the password hash.
170  @param[in,out] salt Used as password hash based on the
171  authentication plugin.
172  @param[in,out] salt_len The length of salt.
173 
174  @retval 0 OK
175  @retval 1 ERROR
176 */
177 typedef int (*set_salt_t)(const char *password, unsigned int password_len,
178  unsigned char *salt, unsigned char *salt_len);
179 
180 /**
181  Plugin API to compare a clear text password with a stored hash
182 
183  @arg hash pointer to the hashed data
184  @arg hash_length length of the hashed data
185  @arg cleartext pointer to the clear text password
186  @arg cleartext_length length of the cleat text password
187  @arg[out] is_error non-zero in case of error extracting the salt
188  @retval 0 the hash was created with that password
189  @retval non-zero the hash was created with a different password
190 */
191 typedef int (*compare_password_with_hash_t)(const char *hash,
192  unsigned long hash_length,
193  const char *cleartext,
194  unsigned long cleartext_length,
195  int *is_error);
196 
197 /**
198  Server authentication plugin descriptor
199 */
201  int interface_version; /** version plugin uses */
202  /**
203  A plugin that a client must use for authentication with this server
204  plugin. Can be NULL to mean "any plugin".
205  */
206  const char *client_auth_plugin;
207 
212 
213  /**
214  Authentication plugin capabilities
215  */
216  const unsigned long authentication_flags;
217 
219 };
220 #endif
unsigned int host_or_ip_length
Length of host_or_ip.
Definition: plugin_auth.h:110
unsigned long additional_auth_string_length
Length of additional password.
Definition: plugin_auth.h:120
const char * auth_string
A corresponding column value from the mysql.user table for the matching account name.
Definition: plugin_auth.h:70
generate_authentication_string_t generate_authentication_string
Definition: plugin_auth.h:209
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:129
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:147
char * user_name
User name as sent by the client and shown in USER().
Definition: plugin_auth.h:59
int password_used
This only affects the "Authentication failed. Password used: %s" error message.
Definition: plugin_auth.h:99
char authenticated_as[MYSQL_USERNAME_LENGTH+1]
Matching account name as found in the mysql.user table.
Definition: plugin_auth.h:82
int interface_version
Definition: plugin_auth.h:201
validate_authentication_string_t validate_authentication_string
Definition: plugin_auth.h:210
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:191
const unsigned long authentication_flags
Authentication plugin capabilities.
Definition: plugin_auth.h:216
#define MYSQL_USERNAME_LENGTH
the max allowed length for a user name
Definition: plugin_auth_common.h:38
const char * additional_auth_string
Additional password.
Definition: plugin_auth.h:115
const char * client_auth_plugin
version plugin uses
Definition: plugin_auth.h:206
uint32_t hash(const void *key, size_t length, const uint32_t initval)
Definition: hash.c:121
This file defines constants and data structures that are the same for both client- and server-side au...
set_salt_t set_salt
Definition: plugin_auth.h:211
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:105
authenticate_user_t authenticate_user
Definition: plugin_auth.h:208
char external_user[512]
The unique user name that was used by the plugin to authenticate.
Definition: plugin_auth.h:89
Provides server plugin access to authentication information.
Definition: plugin_auth.h:54
unsigned long auth_string_length
Length of auth_string.
Definition: plugin_auth.h:75
int(* validate_authentication_string_t)(char *const inbuf, unsigned int buflen)
Plugin API to validate password digest.
Definition: plugin_auth.h:161
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:177
static char * password
Definition: mysql_secure_installation.cc:55
Log info(cout, "NOTE")
Provides plugin access to communication channel.
Definition: plugin_auth_common.h:140
unsigned int user_name_length
Length of user_name.
Definition: plugin_auth.h:64
compare_password_with_hash_t compare_password_with_hash
Definition: plugin_auth.h:218
Server authentication plugin descriptor.
Definition: plugin_auth.h:200