For the complete documentation index, see llms.txt. This page is also available as Markdown.

Authentication Plugin

Plugin API reference: Authentication Plugin. Generated from the MariaDB server headers by doxygen and moxygen.

Plugin API / Plugin Types

API for Authentication plugin. (MYSQL_AUTHENTICATION_PLUGIN)

Groups

Classes

Name
Description

Provides server plugin access to authentication information

Server authentication plugin descriptor

Provides plugin access to communication channel

Macros

Name
Description

MYSQL_AUTHENTICATION_INTERFACE_VERSION

Defined in plugin_auth.h:37


MYSQL_USERNAME_LENGTH

Defined in plugin_auth_common.h:37

the max allowed length for a user name

Typedefs

Return
Name
Description

Provides server plugin access to authentication information

Provides plugin access to communication channel


MYSQL_SERVER_AUTH_INFO

Type: struct st_mysql_server_auth_info

Defined in plugin_auth.h:128

Provides server plugin access to authentication information


MYSQL_PLUGIN_VIO_INFO

Type: struct st_plugin_vio_info

Defined in plugin_auth_common.h:110


MYSQL_PLUGIN_VIO

Type: struct st_plugin_vio

Defined in plugin_auth_common.h:139

Provides plugin access to communication channel

Class Definitions

st_mysql_server_auth_info

Defined in plugin_auth.h:59

Provides server plugin access to authentication information

Public Attributes

Return
Name
Description

const char *

User name as sent by the client and shown in USER(). NULL if the client packet with the user name was not received yet.

unsigned int

Length of user_name

const char *

A corresponding column value from the mysql.user table for the matching account name or the preprocessed value, if preprocess_hash method is not NULL

unsigned long

Length of auth_string

char

Matching account name as found in the mysql.user table. A plugin can override it with another name that will be used by MySQL for authorization, and shown in CURRENT_USER()

char

The unique user name that was used by the plugin to authenticate. Not used by the server. Available through the @EXTERNAL_USER variable.

int

This only affects the "Authentication failed. Password used: @%s" error message. has the following values:

const char *

Set to the name of the connected client host, if it can be resolved, or to its IP address otherwise.

unsigned int

Length of host_or_ip

Current THD pointer (to use with various services)


user_name

Defined in plugin_auth.h:65

User name as sent by the client and shown in USER(). NULL if the client packet with the user name was not received yet.


user_name_length

Defined in plugin_auth.h:70

Length of user_name


auth_string

Defined in plugin_auth.h:77

A corresponding column value from the mysql.user table for the matching account name or the preprocessed value, if preprocess_hash method is not NULL


auth_string_length

Defined in plugin_auth.h:82

Length of auth_string


authenticated_as

Defined in plugin_auth.h:89

Matching account name as found in the mysql.user table. A plugin can override it with another name that will be used by MySQL for authorization, and shown in CURRENT_USER()


external_user

Defined in plugin_auth.h:97

The unique user name that was used by the plugin to authenticate. Not used by the server. Available through the @EXTERNAL_USER variable.


password_used

Defined in plugin_auth.h:110

This only affects the "Authentication failed. Password used: @%s" error message. has the following values:

  • PASSWORD_USED_NO: %s will be NO.

  • PASSWORD_USED_YES: %s will be YES.

  • PASSWORD_USED_NO_MENTION: there will be no %s.

Set it as appropriate or ignore at will.

See also: Values for st_mysql_server_auth_info.password_used


host_or_ip

Defined in plugin_auth.h:116

Set to the name of the connected client host, if it can be resolved, or to its IP address otherwise.


host_or_ip_length

Defined in plugin_auth.h:121

Length of host_or_ip


thd

Type: MYSQL_THD

Defined in plugin_auth.h:126

Current THD pointer (to use with various services)

st_mysql_auth

Defined in plugin_auth.h:133

Server authentication plugin descriptor

Public Attributes

Return
Name
Description

int

version plugin uses

const char *

A plugin that a client must use for authentication with this server plugin. Can be NULL to mean "any plugin".

int(*

Function provided by the plugin which should perform authentication (using the vio functions if necessary) and return 0 if successful. The plugin can also fill the info.authenticated_as field if a different username should be used for authorization.

int(*

Create a password hash (or digest) out of a plain-text password

int(*

Prepare the password hash for authentication.


interface_version

Defined in plugin_auth.h:135

version plugin uses


client_auth_plugin

Defined in plugin_auth.h:140

A plugin that a client must use for authentication with this server plugin. Can be NULL to mean "any plugin".


authenticate_user

Defined in plugin_auth.h:147

Function provided by the plugin which should perform authentication (using the vio functions if necessary) and return 0 if successful. The plugin can also fill the info.authenticated_as field if a different username should be used for authorization.


hash_password

Defined in plugin_auth.h:167

Create a password hash (or digest) out of a plain-text password

Used in SET PASSWORD, GRANT, and CREATE USER to convert user specified plain-text password into a value that will be stored in mysql.user table.

See also: preprocess_hash

Returns

0 for ok, 1 for error

Can be NULL, in this case one will not be able to use SET PASSWORD or PASSWORD('...') in GRANT, CREATE USER, ALTER USER.

Parameters

Parameter
Type
Description

password

plain-text password

password_length

plain-text password length

hash

the digest will be stored there

hash_length

in: hash buffer size out: the actual length of the hash


preprocess_hash

Defined in plugin_auth.h:188

Prepare the password hash for authentication.

Password hash is stored in the authentication_string column of the mysql.user table in a text form. If a plugin needs to preprocess the value somehow before the authentication (e.g. convert from hex or base64 to binary), it can do it in this method. This way the conversion will happen only once, not for every authentication attempt.

The value written to the out buffer will be cached and later made available to the authenticate_user() method in the MYSQL_SERVER_AUTH_INFO::auth_string[] buffer.

Returns

0 for ok, 1 for error

Can be NULL, in this case the mysql.user.authentication_string value will be given to the authenticate_user() method as is, unconverted.

st_plugin_vio_info

Defined in plugin_auth_common.h:101

Public Attributes

Return
Name
Description

enum st_plugin_vio_info::@0

int

it's set, if the protocol is SOCKET or TCP

int


protocol

Defined in plugin_auth_common.h:104


socket

Defined in plugin_auth_common.h:105

it's set, if the protocol is SOCKET or TCP


tls

Defined in plugin_auth_common.h:109

Public Types

Name
Description

@0

Defined in plugin_auth_common.h:103

Value
Description

MYSQL_VIO_INVALID

MYSQL_VIO_TCP

MYSQL_VIO_SOCKET

MYSQL_VIO_PIPE

MYSQL_VIO_MEMORY

st_plugin_vio

Defined in plugin_auth_common.h:115

Provides plugin access to communication channel

Public Attributes

Return
Name
Description

int(*

Plugin provides a pointer reference and this function sets it to the contents of any incoming packet. Returns the packet length, or -1 if the plugin should terminate.

int(*

Plugin provides a buffer with data and the length and this function sends it as a packet. Returns 0 on success, 1 on failure.

void(*

Fills in a st_plugin_vio_info structure, providing the information about the connection.


read_packet

Defined in plugin_auth_common.h:122

Plugin provides a pointer reference and this function sets it to the contents of any incoming packet. Returns the packet length, or -1 if the plugin should terminate.


write_packet

Defined in plugin_auth_common.h:129

Plugin provides a buffer with data and the length and this function sends it as a packet. Returns 0 on success, 1 on failure.


info

Defined in plugin_auth_common.h:137

Fills in a st_plugin_vio_info structure, providing the information about the connection.

This page is licensed: GPLv2

spinner

Last updated

Was this helpful?