Chapter 7 Security Plugins

MySQL includes two plugins that implement native authentication; that is, authentication against passwords stored in the Password column of the mysql.user table. This section describes mysql_native_password, which implements authentication against the mysql.user table using the native password hashing method. For information about mysql_old_password, which implements authentication using the older (pre-4.1) password hashing method, see Section 7.1.2, “The Old Native Authentication Plugin”. For information about these password hashing methods, see Section 2.2.4, “Password Hashing in MySQL”.

The mysql_native_password native authentication plugin is backward compatible. Clients older than MySQL 5.5.7 do not support authentication plugins but do use the native authentication protocol, so they can connect to servers from MySQL 5.5.7 and up.

The following table shows the plugin names on the server and client sides.

The plugin exists in both client and server form:

If an account row specifies no plugin name, the server authenticates the account using either the mysql_native_password or mysql_old_password plugin, depending on whether the password hash value in the Password column used native hashing or the older pre-4.1 hashing method. Clients must match the password in the Password column of the account row.

For general information about pluggable authentication in MySQL, see Section 5.6, “Pluggable Authentication”.

MySQL includes two plugins that implement native authentication; that is, authentication against passwords stored in the Password column of the mysql.user table. This section describes mysql_old_password, which implements authentication against the mysql.user table using the older (pre-4.1) password hashing method. For information about mysql_native_password, which implements authentication using the native password hashing method, see Section 7.1.1, “The Native Authentication Plugin”. For information about these password hashing methods, see Section 2.2.4, “Password Hashing in MySQL”.

The mysql_old_password native authentication plugin is backward compatible. Clients older than MySQL 5.5.7 do not support authentication plugins but do use the native authentication protocol, so they can connect to servers from MySQL 5.5.7 and up.

The following table shows the plugin names on the server and client sides.

The plugin exists in both client and server form:

If an account row specifies no plugin name, the server authenticates the account using either the mysql_native_password or mysql_old_password plugin, depending on whether the password hash value in the Password column used native hashing or the older pre-4.1 hashing method. Clients must match the password in the Password column of the account row.

For general information about pluggable authentication in MySQL, see Section 5.6, “Pluggable Authentication”.

As of MySQL 5.5.16, MySQL Enterprise Edition includes an authentication plugin that enables MySQL Server to use PAM (Pluggable Authentication Modules) to authenticate MySQL users. PAM enables a system to use a standard interface to access various kinds of authentication methods, such as Unix passwords or an LDAP directory.

The PAM authentication plugin provides these capabilities:

The PAM authentication plugin has been tested on Linux and Mac OS X.

The PAM plugin uses the information passed to it by MySQL Server (such as user name, host name, password, and authentication string), plus whatever method is available for PAM lookup. The plugin checks the user credentials against PAM and returns 'Authentication succeeded, Username is user_name' or 'Authentication failed'.

The following table shows the plugin and library file names. The file name suffix might be different on your system. The file location must be the directory named by the plugin_dir system variable. For installation information, see Section 7.1.3.1, “Installing the PAM Authentication Plugin”.

The library file includes only the server-side plugin. As of MySQL 5.5.10, the client-side plugin is built into the libmysqlclient client library. See Section 7.1.5, “The Cleartext Client-Side Authentication Plugin”.

The server-side PAM authentication plugin is included only in MySQL Enterprise Edition. It is not included in MySQL community distributions. The client-side clear-text plugin that communicates with the server-side plugin is built into the MySQL client library and is included in all distributions, including community distributions. This permits clients from any MySQL 5.5.10 or higher distribution to connect to a server that has the server-side plugin loaded.

For general information about pluggable authentication in MySQL, see Section 5.6, “Pluggable Authentication”. For proxy user information, see Section 5.7, “Proxy Users”.

[mysqld]
plugin-load=authentication_pam.so

mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS
    -> WHERE PLUGIN_NAME LIKE 'authentication%';
+--------------------+---------------+
| PLUGIN_NAME        | PLUGIN_STATUS |
+--------------------+---------------+
| authentication_pam | ACTIVE        |
+--------------------+---------------+

CREATE USER user
  IDENTIFIED WITH authentication_pam
  AS 'authentication_string';

CREATE USER user
  IDENTIFIED WITH authentication_pam
  AS 'mysql, root=developer, users=data_entry';

entering auth_pam_server
entering auth_pam_next_token
auth_pam_next_token:reading at [cups,admin=writer,everyone=reader], sep=[,]
auth_pam_next_token:state=PRESPACE, ptr=[cups,admin=writer,everyone=reader],
out=[]
auth_pam_next_token:state=IDENT, ptr=[cups,admin=writer,everyone=reader],
out=[]
auth_pam_next_token:state=AFTERSPACE, ptr=[,admin=writer,everyone=reader],
out=[cups]
auth_pam_next_token:state=DELIMITER, ptr=[,admin=writer,everyone=reader],
out=[cups]
auth_pam_next_token:state=DONE, ptr=[,admin=writer,everyone=reader],
out=[cups]
leaving auth_pam_next_token on
/Users/gkodinov/mysql/work/x-5.5.16-release-basket/release/plugin/pam-authentication-plugin/src/parser.c:191
auth_pam_server:password 12345qq received
auth_pam_server:pam_start rc=0
auth_pam_server:pam_set_item(PAM_RUSER,gkodinov) rc=0
auth_pam_server:pam_set_item(PAM_RHOST,localhost) rc=0
entering auth_pam_server_conv
auth_pam_server_conv:PAM_PROMPT_ECHO_OFF [Password:] received
leaving auth_pam_server_conv on
/Users/gkodinov/mysql/work/x-5.5.16-release-basket/release/plugin/pam-authentication-plugin/src/authentication_pam.c:257
auth_pam_server:pam_authenticate rc=0
auth_pam_server:pam_acct_mgmt rc=0
auth_pam_server:pam_setcred(PAM_ESTABLISH_CRED) rc=0
auth_pam_server:pam_get_item rc=0
auth_pam_server:pam_setcred(PAM_DELETE_CRED) rc=0
entering auth_pam_map_groups
entering auth_pam_walk_namevalue_list
auth_pam_walk_namevalue_list:reading at: [admin=writer,everyone=reader]
entering auth_pam_next_token
auth_pam_next_token:reading at [admin=writer,everyone=reader], sep=[=]
auth_pam_next_token:state=PRESPACE, ptr=[admin=writer,everyone=reader], out=[]
auth_pam_next_token:state=IDENT, ptr=[admin=writer,everyone=reader], out=[]
auth_pam_next_token:state=AFTERSPACE, ptr=[=writer,everyone=reader],
out=[admin]
auth_pam_next_token:state=DELIMITER, ptr=[=writer,everyone=reader],
out=[admin]
auth_pam_next_token:state=DONE, ptr=[=writer,everyone=reader], out=[admin]
leaving auth_pam_next_token on
/Users/gkodinov/mysql/work/x-5.5.16-release-basket/release/plugin/pam-authentication-plugin/src/parser.c:191
auth_pam_walk_namevalue_list:name=[admin]
entering auth_pam_next_token
auth_pam_next_token:reading at [writer,everyone=reader], sep=[,]
auth_pam_next_token:state=PRESPACE, ptr=[writer,everyone=reader], out=[]
auth_pam_next_token:state=IDENT, ptr=[writer,everyone=reader], out=[]
auth_pam_next_token:state=AFTERSPACE, ptr=[,everyone=reader], out=[writer]
auth_pam_next_token:state=DELIMITER, ptr=[,everyone=reader], out=[writer]
auth_pam_next_token:state=DONE, ptr=[,everyone=reader], out=[writer]
leaving auth_pam_next_token on
/Users/gkodinov/mysql/work/x-5.5.16-release-basket/release/plugin/pam-authentication-plugin/src/parser.c:191
walk, &error_namevalue_list:value=[writer]
entering auth_pam_map_group_to_user
auth_pam_map_group_to_user:pam_user=gkodinov, name=admin, value=writer
examining member root
examining member gkodinov
substitution was made to mysql user writer
leaving auth_pam_map_group_to_user on
/Users/gkodinov/mysql/work/x-5.5.16-release-basket/release/plugin/pam-authentication-plugin/src/authentication_pam.c:118
auth_pam_walk_namevalue_list:found mapping
leaving auth_pam_walk_namevalue_list on
/Users/gkodinov/mysql/work/x-5.5.16-release-basket/release/plugin/pam-authentication-plugin/src/parser.c:270
auth_pam_walk_namevalue_list returned 0
leaving auth_pam_map_groups on
/Users/gkodinov/mysql/work/x-5.5.16-release-basket/release/plugin/pam-authentication-plugin/src/authentication_pam.c:171
auth_pam_server:authenticated_as=writer
auth_pam_server: rc=0
leaving auth_pam_server on
/Users/gkodinov/mysql/work/x-5.5.16-release-basket/release/plugin/pam-authentication-plugin/src/authentication_pam.c:429

As of MySQL 5.5.16, MySQL Enterprise Edition for Windows includes an authentication plugin that performs external authentication on Windows, enabling MySQL Server to use native Windows services to authenticate client connections. Users who have logged in to Windows can connect from MySQL client programs to the server based on the information in their environment without specifying an additional password.

The client and server exchange data packets in the authentication handshake. As a result of this exchange, the server creates a security context object that represents the identity of the client in the Windows OS. This identity includes the name of the client account. The Windows authentication plugin uses the identity of the client to check whether it is a given account or a member of a group. By default, negotiation uses Kerberos to authenticate, then NTLM if Kerberos is unavailable.

The Windows authentication plugin provides these capabilities:

The following table shows the plugin and library file names. The file location must be the directory named by the plugin_dir system variable. For installation information, see Section 7.1.4.1, “Installing the Windows Authentication Plugin”.

The library file includes only the server-side plugin. As of MySQL 5.5.13, the client-side plugin is built into the libmysqlclient client library.

The server-side Windows authentication plugin is included only in MySQL Enterprise Edition. It is not included in MySQL community distributions. The client-side plugin is included in all distributions, including community distributions. This permits clients from any 5.5.13 or higher distribution to connect to a server that has the server-side plugin loaded.

The Windows authentication plugin is supported on any version of Windows supported by MySQL 5.5 (see http://www.mysql.com/support/supportedplatforms/database.html). It requires MySQL Server 5.5.16 or higher.

For general information about pluggable authentication in MySQL, see Section 5.6, “Pluggable Authentication”. For proxy user information, see Section 5.7, “Proxy Users”.

[mysqld]
plugin-load=authentication_windows.dll

mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS
    -> WHERE PLUGIN_NAME LIKE 'authentication%';
+------------------------+---------------+
| PLUGIN_NAME            | PLUGIN_STATUS |
+------------------------+---------------+
| authentication_windows | ACTIVE        |
+------------------------+---------------+

CREATE USER sql_admin
  IDENTIFIED WITH authentication_windows
  AS 'Rafal, Tasha, Administrators, "Power Users"';

C:\> mysql --user=sql_admin

'win_group = sql_user1, win_user = sql_user2'

CREATE USER sql_accounting
  IDENTIFIED WITH authentication_windows
  AS 'SomeDomain\\Accounting';

As of MySQL 5.5.10, a client-side authentication plugin is available that sends the password to the server without hashing or encryption. This plugin is built into the MySQL client library.

The following table shows the plugin name.

With native MySQL authentication, the client performs one-way hashing on the password before sending it to the server. This enables the client to avoid sending the password in clear text. See Section 2.2.4, “Password Hashing in MySQL”. However, because the hash algorithm is one way, the original password cannot be recovered on the server side.

One-way hashing cannot be done for authentication schemes that require the server to receive the password as entered on the client side. In such cases, the mysql_clear_password client-side plugin can be used to send the password to the server in clear text. There is no corresponding server-side plugin. Rather, the client-side plugin can be used by any server-side plugin that needs a clear text password. (The PAM authentication plugin is one such; see Section 7.1.3, “The PAM Authentication Plugin”.)

For general information about pluggable authentication in MySQL, see Section 5.6, “Pluggable Authentication”.

As of MySQL 5.5.27, to make inadvertent use of this plugin less likely, it is required that clients explicitly enable it. This can be done several ways:

As of MySQL 5.5.10, a server-side authentication plugin is available that authenticates clients that connect from the local host through the Unix socket file. This plugin works only on Linux systems.

The source code for this plugin can be examined as a relatively simple example demonstrating how to write a loadable authentication plugin.

The following table shows the plugin and library file names. The file name suffix might differ on your system. The file location is the directory named by the plugin_dir system variable. For installation information, see Section 5.6, “Pluggable Authentication”.

The auth_socket authentication plugin authenticates clients that connect from the local host through the Unix socket file. The plugin uses the SO_PEERCRED socket option to obtain information about the user running the client program. Thus, the plugin can be built only on systems that support the SO_PEERCRED option, such as Linux.

The plugin checks whether the user name matches the MySQL user name specified by the client program to the server, and permits the connection only if the names match.

Suppose that a MySQL account is created for a user named valerie who is to be authenticated by the auth_socket plugin for connections from the local host through the socket file:

CREATE USER 'valerie'@'localhost' IDENTIFIED WITH auth_socket;

If a user on the local host with a login name of stefanie invokes mysql with the option --user=valerie to connect through the socket file, the server uses auth_socket to authenticate the client. The plugin determines that the --user option value (valerie) differs from the client user's name (stephanie) and refuses the connection. If a user named valerie tries the same thing, the plugin finds that the user name and the MySQL user name are both valerie and permits the connection. However, the plugin refuses the connection even for valerie if the connection is made using a different protocol, such as TCP/IP.

For general information about pluggable authentication in MySQL, see Section 5.6, “Pluggable Authentication”.

MySQL includes a test plugin that authenticates using MySQL native authentication, but is a loadable plugin (not built in) and must be installed prior to use. It can authenticate against either normal or older (shorter) password hash values.

This plugin is intended for testing and development purposes, and not for use in production environments. The test plugin source code is separate from the server source, unlike the built-in native plugin, so it can be examined as a relatively simple example demonstrating how to write a loadable authentication plugin.

The following table shows the plugin and library file names. The file name suffix might differ on your system. The file location is the directory named by the plugin_dir system variable. For installation information, see Section 5.6, “Pluggable Authentication”.

Because the test plugin authenticates the same way as native MySQL authentication, provide the usual --user and --password options that you normally use for accounts that use native authentication when you connect to the server. For example:

shell> mysql --user=your_name --password=your_pass

For general information about pluggable authentication in MySQL, see Section 5.6, “Pluggable Authentication”.

This section describes how to install MySQL Enterprise Audit, which is implemented using the audit_log plugin. For general information about installing plugins, see Installing and Uninstalling Plugins.

To be usable by the server, the plugin library file must be located in the MySQL plugin directory (the directory named by the plugin_dir system variable). If necessary, set the value of plugin_dir at server startup to tell the server the plugin directory location.

The plugin library file base name is audit_log. The file name suffix differs per platform (for example, .so for Unix and Unix-like systems, .dll for Windows).

To load the plugin at server startup, use the --plugin-load option to name the library file that contains the plugin. With this plugin-loading method, the option must be given each time the server starts. For example, put the following lines in your my.cnf file (adjust the .so suffix for your platform as necessary):

[mysqld]
plugin-load=audit_log.so

Alternatively, to register the plugin at runtime, use this statement (adjust the suffix as necessary):

INSTALL PLUGIN audit_log SONAME 'audit_log.so';

INSTALL PLUGIN loads the plugin, and also registers it in the mysql.plugins table to cause the plugin to be loaded for each subsequent normal server startup.

To verify plugin installation, examine the INFORMATION_SCHEMA.PLUGINS table or use the SHOW PLUGINS statement (see Obtaining Server Plugin Information). For example:

mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS
    -> WHERE PLUGIN_NAME LIKE 'audit%';
+-------------+---------------+
| PLUGIN_NAME | PLUGIN_STATUS |
+-------------+---------------+
| audit_log   | ACTIVE        |
+-------------+---------------+

If the plugin has been previously registered with INSTALL PLUGIN or is loaded with --plugin-load, you can use the --audit-log option at server startup to control plugin activation. For example, to load the plugin at startup and prevent it from being removed at runtime, use these options:

[mysqld]
plugin-load=audit_log.so
audit-log=FORCE_PLUS_PERMANENT

If it is desired to prevent the server from running without the audit plugin, use --audit-log with a value of FORCE or FORCE_PLUS_PERMANENT to force server startup to fail if the plugin does not initialize successfully.

For additional information about the parameters used to configure operation of the audit_log plugin, see Section 7.2.7, “Audit Log Options and System Variables”.

Audit log file contents are not encrypted. See Section 7.2.2, “MySQL Enterprise Audit Security Considerations”.

Contents of the audit log file produced by the audit_log plugin are not encrypted and may contain sensitive information, such as the text of SQL statements. For security reasons, this file should be written to a directory accessible only to the MySQL server and users with a legitimate reason to view the log. The default file is audit.log in the data directory. This can be changed by setting the audit_log_file system variable at server startup.

Audit log file contents are not encrypted. See Section 7.2.2, “MySQL Enterprise Audit Security Considerations”.

The audit log file is written as XML, using UTF-8 (up to 4 bytes per character). The root element is <AUDIT>. The closing </AUDIT> tag of the root element is written when the audit log plugin terminates, so the tag is not present in the file while the plugin is active.

The root element contains <AUDIT_RECORD> elements. Each <AUDIT_RECORD> element has an empty body; all audit record fields are represented by element attributes.

MySQL 5.7 changed audit log file output to a new format that has better compatibility with Oracle Audit Vault. This new format was backported to MySQL 5.5 as of MySQL 5.5.34 and it is possible to select either the old or new format using the audit_log_format system variable, which has permitted values of OLD and NEW (default OLD).

If you change the value of audit_log_format, use this procedure to avoid writing log entries in one format to an existing log file that contains entries in a different format:

Here is a sample log file in the default (old) format, reformatted slightly for readability:

<?xml version="1.0" encoding="utf-8"?>
<AUDIT>
  <AUDIT_RECORD
    TIMESTAMP="2012-08-02T14:52:12"
    NAME="Audit"
    SERVER_ID="1"
    VERSION="1"
    STARTUP_OPTIONS="--port=3306"
    OS_VERSION="i686-Linux"
    MYSQL_VERSION="5.5.28-debug-log"/>
  <AUDIT_RECORD
    TIMESTAMP="2012-08-02T14:52:41"
    NAME="Connect"
    CONNECTION_ID="1"
    STATUS="0"
    USER="root"
    PRIV_USER="root"
    OS_LOGIN=""
    PROXY_USER=""
    HOST="localhost"
    IP="127.0.0.1"
    DB=""/>
  <AUDIT_RECORD
    TIMESTAMP="2012-08-02T14:53:45"
    NAME="Query"
    CONNECTION_ID="1"
    STATUS="0"
    SQLTEXT="INSERT INTO t1 () VALUES()"/>
  <AUDIT_RECORD
    TIMESTAMP="2012-08-02T14:53:51"
    NAME="Quit"
    CONNECTION_ID="1"
    STATUS="0"/>
  <AUDIT_RECORD
    TIMESTAMP="2012-08-06T14:21:03"
    NAME="NoAudit"
    SERVER_ID="1"/>
</AUDIT>

Attributes of <AUDIT_RECORD> elements have these characteristics:

This section describes how the audit_log plugin performs logging and the system variables that control how logging occurs. It assumes familiarity with the log file format described in Section 7.2.3, “The Audit Log File”.

When the audit log plugin opens its log file, it checks whether the XML declaration and opening <AUDIT> root element tag must be written and writes them if so. When the audit log plugin terminates, it writes a closing </AUDIT> tag to the file.

If the log file exists at open time, the plugin checks whether the file ends with an </AUDIT> tag and truncates it if so before writing any <AUDIT_RECORD> elements. If the log file exists but does not end with </AUDIT> or the </AUDIT> tag cannot be truncated, the plugin considers the file malformed and fails to initialize. This can occur if the server crashes or is killed with the audit log plugin running. No logging occurs until the problem is rectified. Check the error log for diagnostic information:

[ERROR] Plugin 'audit_log' init function returned error.

To deal with this problem, either remove or rename the malformed log file and restart the server.

The MySQL server calls the audit log plugin to write an <AUDIT_RECORD> element whenever an auditable event occurs, such as when it completes execution of an SQL statement received from a client. Typically the first <AUDIT_RECORD> element written after server startup has the server description and startup options. Elements following that one represent events such as client connect and disconnect events, executed SQL statements, and so forth. Only top-level statements are logged, not statements within stored programs such as triggers or stored procedures. Contents of files referenced by statements such as LOAD DATA INFILE are not logged.

To permit control over how logging occurs, the audit_log plugin provides several system variables, described following. For more information, see Section 7.2.7, “Audit Log Options and System Variables”.

The audit_log_policy system variable controls what kinds of information the plugin writes. By default, this variable is set to ALL (write all auditable events), but also permits values of LOGINS or QUERIES to log only login or query events, or NONE to disable logging.

This section describes the command options and system variables that control operation of MySQL Enterprise Audit. If values specified at startup time are incorrect, the audit_log plugin may fail to initialize properly and the server does not load it. In this case, the server may also produce error messages for other audit log settings because it will not recognize them.

To control the activation of the audit_log plugin, use this option:

If the audit_log plugin is enabled, it exposes several system variables that permit control over logging:

mysql> SHOW VARIABLES LIKE 'audit_log%';
+--------------------------+--------------+
| Variable_name            | Value        |
+--------------------------+--------------+
| audit_log_buffer_size    | 1048576      |
| audit_log_file           | audit.log    |
| audit_log_flush          | OFF          |
| audit_log_policy         | ALL          |
| audit_log_rotate_on_size | 0            |
| audit_log_strategy       | ASYNCHRONOUS |
+--------------------------+--------------+

You can set any of these variables at server startup, and some of them at runtime.

MySQL Enterprise Audit is subject to these general restrictions:

MySQL Cluster.  It is possible to use MySQL Enterprise Audit with MySQL Cluster, subject to the following conditions: