Table of Contents
When thinking about security within a MySQL installation, you should consider a wide range of possible topics and how they affect the security of your MySQL server and related applications:
General factors that affect security. These include choosing good passwords, not granting unnecessary privileges to users, ensuring application security by preventing SQL injections and data corruption, and others. See Section 6.1, “General Security Issues”.
Security of the installation itself. The data files, log files, and the all the application files of your installation should be protected to ensure that they are not readable or writable by unauthorized parties. For more information, see Section 2.10, “Postinstallation Setup and Testing”.
Access control and security within the database system itself, including the users and databases granted with access to the databases, views and stored programs in use within the database. For more information, see Section 6.2, “The MySQL Access Privilege System”, and Section 6.3, “MySQL User Account Management”.
The features offered by security-related plugins. See Section 6.4, “Security Plugins”.
Network security of MySQL and your system. The security is related to the grants for individual users, but you may also wish to restrict MySQL so that it is available only locally on the MySQL server host, or to a limited set of other hosts.
Ensure that you have adequate and appropriate backups of your database files, configuration and log files. Also be sure that you have a recovery solution in place and test that you are able to successfully recover the information from your backups. See Chapter 7, Backup and Recovery.
This section describes general security issues to be aware of and what you can do to make your MySQL installation more secure against attack or misuse. For information specifically about the access control system that MySQL uses for setting up user accounts and checking database access, see Section 2.10, “Postinstallation Setup and Testing”.
For answers to some questions that are often asked about MySQL Server security issues, see Section A.9, “MySQL 5.7 FAQ: Security”.
Anyone using MySQL on a computer connected to the Internet should read this section to avoid the most common security mistakes.
In discussing security, it is necessary to consider fully protecting the entire server host (not just the MySQL server) against all types of applicable attacks: eavesdropping, altering, playback, and denial of service. We do not cover all aspects of availability and fault tolerance here.
MySQL uses security based on Access Control Lists (ACLs) for all connections, queries, and other operations that users can attempt to perform. There is also support for SSL-encrypted connections between MySQL clients and servers. Many of the concepts discussed here are not specific to MySQL at all; the same general ideas apply to almost all applications.
When running MySQL, follow these guidelines:
Do not ever give anyone (except MySQL
root
accounts) access to the
user
table in the mysql
database! This is critical.
Learn how the MySQL access privilege system works (see
Section 6.2, “The MySQL Access Privilege System”). Use the
GRANT
and
REVOKE
statements to control
access to MySQL. Do not grant more privileges than necessary.
Never grant privileges to all hosts.
Checklist:
Try mysql -u root
. If you are able to
connect successfully to the server without being asked for
a password, anyone can connect to your MySQL server as the
MySQL root
user with full privileges!
Review the MySQL installation instructions, paying
particular attention to the information about setting a
root
password. See
Section 2.10.4, “Securing the Initial MySQL Accounts”.
Use the SHOW GRANTS
statement to check which accounts have access to what.
Then use the REVOKE
statement to remove those privileges that are not
necessary.
Do not store cleartext passwords in your database. If your
computer becomes compromised, the intruder can take the full
list of passwords and use them. Instead, use
SHA2()
,
SHA1()
,
MD5()
, or some other one-way
hashing function and store the hash value.
To prevent password recovery using rainbow tables, do not use these functions on a plain password; instead, choose some string to be used as a salt, and use hash(hash(password)+salt) values.
Do not choose passwords from dictionaries. Special programs exist to break passwords. Even passwords like “xfish98” are very bad. Much better is “duag98” which contains the same word “fish” but typed one key to the left on a standard QWERTY keyboard. Another method is to use a password that is taken from the first characters of each word in a sentence (for example, “Four score and seven years ago” results in a password of “Fsasya”). The password is easy to remember and type, but difficult to guess for someone who does not know the sentence. In this case, you can additionally substitute digits for the number words to obtain the phrase “4 score and 7 years ago”, yielding the password “4sa7ya” which is even more difficult to guess.
Invest in a firewall. This protects you from at least 50% of all types of exploits in any software. Put MySQL behind the firewall or in a demilitarized zone (DMZ).
Checklist:
Try to scan your ports from the Internet using a tool such
as nmap
. MySQL uses port 3306 by
default. This port should not be accessible from untrusted
hosts. As a simple way to check whether your MySQL port is
open, try the following command from some remote machine,
where server_host
is the host
name or IP address of the host on which your MySQL server
runs:
shell> telnet server_host
3306
If telnet hangs or the connection is refused, the port is blocked, which is how you want it to be. If you get a connection and some garbage characters, the port is open, and should be closed on your firewall or router, unless you really have a good reason to keep it open.
Applications that access MySQL should not trust any data entered by users, and should be written using proper defensive programming techniques. See Section 6.1.7, “Client Programming Security Guidelines”.
Do not transmit plain (unencrypted) data over the Internet. This information is accessible to everyone who has the time and ability to intercept it and use it for their own purposes. Instead, use an encrypted protocol such as SSL or SSH. MySQL supports internal SSL connections. Another technique is to use SSH port-forwarding to create an encrypted (and compressed) tunnel for the communication.
Learn to use the tcpdump and strings utilities. In most cases, you can check whether MySQL data streams are unencrypted by issuing a command like the following:
shell> tcpdump -l -i eth0 -w - src or dst port 3306 | strings
This works under Linux and should work with small modifications under other systems.
If you do not see cleartext data, this does not always mean that the information actually is encrypted. If you need high security, consult with a security expert.
Passwords occur in several contexts within MySQL. The following sections provide guidelines that enable end users and administrators to keep these passwords secure and avoid exposing them. There is also a discussion of how MySQL uses password hashing internally and of a plugin that you can use to enforce stricter passwords.
MySQL users should use the following guidelines to keep passwords secure.
When you run a client program to connect to the MySQL server, it is inadvisable to specify your password in a way that exposes it to discovery by other users. The methods you can use to specify your password when you run client programs are listed here, along with an assessment of the risks of each method. In short, the safest methods are to have the client program prompt for the password or to specify the password in a properly protected option file.
Use the mysql_config_editor utility,
which enables you to store authentication credentials in an
encrypted login path file named
.mylogin.cnf
. The file can be read
later by MySQL client programs to obtain authentication
credentials for connecting to MySQL Server. See
Section 4.6.6, “mysql_config_editor — MySQL Configuration Utility”.
Use a
-p
or
your_pass
--password=
option on the command line. For example:
your_pass
shell> mysql -u francis -pfrank db_name
This is convenient but insecure. On some systems, your password becomes visible to system status programs such as ps that may be invoked by other users to display command lines. MySQL clients typically overwrite the command-line password argument with zeros during their initialization sequence. However, there is still a brief interval during which the value is visible. Also, on some systems this overwriting strategy is ineffective and the password remains visible to ps. (SystemV Unix systems and perhaps others are subject to this problem.)
If your operating environment is set up to display your current command in the title bar of your terminal window, the password remains visible as long as the command is running, even if the command has scrolled out of view in the window content area.
Use the -p
or --password
option on the command line with no password value specified.
In this case, the client program solicits the password
interactively:
shell> mysql -u francis -p db_name
Enter password: ********
The “*
” characters indicate
where you enter your password. The password is not displayed
as you enter it.
It is more secure to enter your password this way than to specify it on the command line because it is not visible to other users. However, this method of entering a password is suitable only for programs that you run interactively. If you want to invoke a client from a script that runs noninteractively, there is no opportunity to enter the password from the keyboard. On some systems, you may even find that the first line of your script is read and interpreted (incorrectly) as your password.
Store your password in an option file. For example, on Unix,
you can list your password in the
[client]
section of the
.my.cnf
file in your home directory:
[client] password=your_pass
To keep the password safe, the file should not be accessible
to anyone but yourself. To ensure this, set the file access
mode to 400
or 600
.
For example:
shell> chmod 600 .my.cnf
To name from the command line a specific option file
containing the password, use the
--defaults-file=
option, where file_name
file_name
is the full
path name to the file. For example:
shell> mysql --defaults-file=/home/francis/mysql-opts
Section 4.2.6, “Using Option Files”, discusses option files in more detail.
Store your password in the MYSQL_PWD
environment variable. See
Section 2.12, “Environment Variables”.
This method of specifying your MySQL password must be
considered extremely insecure and
should not be used. Some versions of ps
include an option to display the environment of running
processes. On some systems, if you set
MYSQL_PWD
, your password is exposed to
any other user who runs ps. Even on
systems without such a version of ps, it
is unwise to assume that there are no other methods by which
users can examine process environments.
On Unix, the mysql client writes a record of
executed statements to a history file (see
Section 4.5.1.3, “mysql Logging”). By default, this file is named
.mysql_history
and is created in your home
directory. Passwords can be written as plain text in SQL
statements such as CREATE USER
and ALTER USER
, so if you use
these statements, they are logged in the history file. To keep
this file safe, use a restrictive access mode, the same way as
described earlier for the .my.cnf
file.
If your command interpreter is configured to maintain a history,
any file in which the commands are saved will contain MySQL
passwords entered on the command line. For example,
bash uses
~/.bash_history
. Any such file should have
a restrictive access mode.
Database administrators should use the following guidelines to keep passwords secure.
MySQL stores passwords for user accounts in the
mysql.user
table. Access to this table should
never be granted to any nonadministrative accounts.
Account passwords can be expired so that users must reset them. See Section 6.3.6, “Password Expiration Policy”, and Section 6.3.7, “Password Expiration and Sandbox Mode”.
The validate_password
plugin can be used to
enforce a policy on acceptable password. See
Section 6.4.2, “The Password Validation Plugin”.
A user who has access to modify the plugin directory (the value
of the plugin_dir
system
variable) or the my.cnf
file that specifies
the location of the plugin directory can replace plugins and
modify the capabilities provided by plugins, including
authentication plugins.
Files such as log files to which passwords might be written should be protected. See Section 6.1.2.3, “Passwords and Logging”.
Passwords can be written as plain text in SQL statements such as
CREATE USER
,
GRANT
, SET
PASSWORD
, and statements that invoke the
PASSWORD()
function. If such
statements are logged by the MySQL server as written, passwords
in them become visible to anyone with access to the logs.
In MySQL 5.7, statement logging avoids writing passwords in cleartext for the following statements:
CREATE USER ... IDENTIFIED BY ... ALTER USER ... IDENTIFIED BY ... GRANT ... IDENTIFIED BY ... SET PASSWORD ... SLAVE START ... PASSWORD = ... CREATE SERVER ... OPTIONS(... PASSWORD ...) ALTER SERVER ... OPTIONS(... PASSWORD ...)
Passwords in those statements are rewritten to not appear
literally in statement text written to the general query log,
slow query log, and binary log. Rewriting does not apply to
other statements. In particular,
INSERT
or
UPDATE
statements for the
mysql.user
table that refer to literal
passwords are logged as is, so you should avoid such statements.
(Direct manipulation of grant tables is discouraged, anyway.)
For the general query log, password rewriting can be suppressed
by starting the server with the
--log-raw
option. For security
reasons, this option is not recommended for production use. For
diagnostic purposes, it may be useful to see the exact text of
statements as received by the server.
Contents of the audit log file produced by the audit log plugin are not encrypted. 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. See Section 6.4.4.2, “Audit Log Plugin Security Considerations”.
Statements received by the server may be rewritten if a query
rewrite plugin is installed (see
Query Rewrite Plugins). In this case, the
--log-raw
option affects
statement logging as follows:
To guard log files against unwarranted exposure, locate them in
a directory that restricts access to the server and the database
administrator. If the server logs to tables in the
mysql
database, grant access to those tables
only to the database administrator.
Replication slaves store the password for the replication master
in the master info repository, which can be either a file or a
table (see Section 17.2.4, “Replication Relay and Status Logs”). Ensure that the
repository can be accessed only by the database administrator.
An alternative to storing the password in a file is to use the
START SLAVE
statement to specify
credentials for connecting to the master.
Use a restricted access mode to protect database backups that include log tables or log files containing passwords.
The information in this section applies fully only before
MySQL 5.7.5, and only for accounts that use the
mysql_native_password
or
mysql_old_password
authentication plugins.
Support for pre-4.1 password hashes is removed in MySQL 5.7.5.
This includes removal of the
mysql_old_password
authentication plugin
and the OLD_PASSWORD()
function. Also, secure_auth
cannot be disabled, and
old_passwords
cannot be set
to 1.
As of MySQL 5.7.5, only the information about 4.1 password
hashes and the mysql_native_password
authentication plugin remains relevant.
MySQL lists user accounts in the user
table
of the mysql
database. Each MySQL account can
be assigned a password, although the user
table does not store the cleartext version of the password, but
a hash value computed from it.
MySQL uses passwords in two phases of client/server communication:
When a client attempts to connect to the server, there is an
initial authentication step in which the client must present
a password that has a hash value matching the hash value
stored in the user
table for the account
the client wants to use.
After the client connects, it can (if it has sufficient
privileges) set or change the password hash for accounts
listed in the user
table. The client can
do this by using the
PASSWORD()
function to
generate a password hash, or by using a password-generating
statement (CREATE USER
,
GRANT
, or
SET PASSWORD
).
In other words, the server checks hash
values during authentication when a client first attempts to
connect. The server generates hash values
if a connected client invokes the
PASSWORD()
function or uses a
password-generating statement to set or change a password.
Password hashing methods in MySQL have the history described
following. These changes are illustrated by changes in the
result from the PASSWORD()
function that computes password hash values and in the structure
of the user
table where passwords are stored.
The original hashing method produced a 16-byte string. Such hashes look like this:
mysql> SELECT PASSWORD('mypass');
+--------------------+
| PASSWORD('mypass') |
+--------------------+
| 6f8c114b58f2ce9e |
+--------------------+
To store account passwords, the Password
column of the user
table was at this point 16
bytes long.
MySQL 4.1 introduced password hashing that provided better security and reduced the risk of passwords being intercepted. There were several aspects to this change:
Different format of password values produced by the
PASSWORD()
function
Widening of the Password
column
Control over the default hashing method
Control over the permitted hashing methods for clients attempting to connect to the server
The changes in MySQL 4.1 took place in two stages:
MySQL 4.1.0 used a preliminary version of the 4.1 hashing method. This method was short lived and the following discussion says nothing more about it.
In MySQL 4.1.1, the hashing method was modified to produce a longer 41-byte hash value:
mysql> SELECT PASSWORD('mypass');
+-------------------------------------------+
| PASSWORD('mypass') |
+-------------------------------------------+
| *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 |
+-------------------------------------------+
The longer password hash format has better cryptographic properties, and client authentication based on long hashes is more secure than that based on the older short hashes.
To accommodate longer password hashes, the
Password
column in the
user
table was changed at this point to
be 41 bytes, its current length.
A widened Password
column can store
password hashes in both the pre-4.1 and 4.1 formats. The
format of any given hash value can be determined two ways:
The length: 4.1 and pre-4.1 hashes are 41 and 16 bytes, respectively.
Password hashes in the 4.1 format always begin with a
“*
” character, whereas
passwords in the pre-4.1 format never do.
To permit explicit generation of pre-4.1 password hashes, two additional changes were made:
The OLD_PASSWORD()
function was added, which returns hash values in the
16-byte format.
For compatibility purposes, the
old_passwords
system
variable was added, to enable DBAs and applications
control over the hashing method. The default
old_passwords
value of
0 causes hashing to use the 4.1 method (41-byte hash
values), but setting
old_passwords=1
causes
hashing to use the pre-4.1 method. In this case,
PASSWORD()
produces
16-byte values and is equivalent to
OLD_PASSWORD()
To permit DBAs control over how clients are permitted to
connect, the secure_auth
system variable was added. Starting the server with this
variable disabled or enabled permits or prohibits clients to
connect using the older pre-4.1 password hashing method.
Before MySQL 5.6.5,
secure_auth
is disabled by
default. As of 5.6.5,
secure_auth
is enabled by
default to promote a more secure default configuration DBAs
can disable it at their discretion, but this is not
recommended, and pre-4.1 password hashes are deprecated and
should be avoided. (For account upgrade instructions, see
Section 6.4.1.3, “Migrating Away from Pre-4.1 Password Hashing and the mysql_old_password
Plugin”.)
In addition, the mysql client supports a
--secure-auth
option that is
analogous to secure_auth
,
but from the client side. It can be used to prevent
connections to less secure accounts that use pre-4.1
password hashing. This option is disabled by default before
MySQL 5.6.7, enabled thereafter.
The widening of the Password
column in MySQL
4.1 from 16 bytes to 41 bytes affects installation or upgrade
operations as follows:
If you perform a new installation of MySQL, the
Password
column is made 41 bytes long
automatically.
Upgrades from MySQL 4.1 or later to current versions of
MySQL should not give rise to any issues in regard to the
Password
column because both versions use
the same column length and password hashing method.
For upgrades from a pre-4.1 release to 4.1 or later, you must upgrade the system tables after upgrading. (See Section 4.4.7, “mysql_upgrade — Check and Upgrade MySQL Tables”.)
The 4.1 hashing method is understood only by MySQL 4.1 (and newer) servers and clients, which can result in some compatibility problems. A 4.1 or newer client can connect to a pre-4.1 server, because the client understands both the pre-4.1 and 4.1 password hashing methods. However, a pre-4.1 client that attempts to connect to a 4.1 or newer server may run into difficulties. For example, a 4.0 mysql client may fail with the following error message:
shell> mysql -h localhost -u root
Client does not support authentication protocol requested
by server; consider upgrading MySQL client
This phenomenon also occurs for attempts to use the older PHP
mysql
extension after upgrading to MySQL 4.1
or newer. (See Common Problems with MySQL and PHP.)
The following discussion describes the differences between the pre-4.1 and 4.1 hashing methods, and what you should do if you upgrade your server but need to maintain backward compatibility with pre-4.1 clients. (However, permitting connections by old clients is not recommended and should be avoided if possible.) Additional information can be found in Section B.5.2.4, “Client does not support authentication protocol”. This information is of particular importance to PHP programmers migrating MySQL databases from versions older than 4.1 to 4.1 or higher.
The differences between short and long password hashes are relevant both for how the server uses passwords during authentication and for how it generates password hashes for connected clients that perform password-changing operations.
The way in which the server uses password hashes during
authentication is affected by the width of the
Password
column:
If the column is short, only short-hash authentication is used.
If the column is long, it can hold either short or long hashes, and the server can use either format:
Pre-4.1 clients can connect, but because they know only about the pre-4.1 hashing method, they can authenticate only using accounts that have short hashes.
4.1 and later clients can authenticate using accounts that have short or long hashes.
Even for short-hash accounts, the authentication process is actually a bit more secure for 4.1 and later clients than for older clients. In terms of security, the gradient from least to most secure is:
Pre-4.1 client authenticating with short password hash
4.1 or later client authenticating with short password hash
4.1 or later client authenticating with long password hash
The way in which the server generates password hashes for
connected clients is affected by the width of the
Password
column and by the
old_passwords
system variable.
A 4.1 or later server generates long hashes only if certain
conditions are met: The Password
column must
be wide enough to hold long values and
old_passwords
must not be set
to 1.
Those conditions apply as follows:
The Password
column must be wide enough
to hold long hashes (41 bytes). If the column has not been
updated and still has the pre-4.1 width of 16 bytes, the
server notices that long hashes cannot fit into it and
generates only short hashes when a client performs
password-changing operations using the
PASSWORD()
function or a
password-generating statement. This is the behavior that
occurs if you have upgraded from a version of MySQL older
than 4.1 to 4.1 or later but have not yet run the
mysql_upgrade program to widen the
Password
column.
If the Password
column is wide, it can
store either short or long password hashes. In this case,
the PASSWORD()
function and
password-generating statements generate long hashes unless
the server was started with the
old_passwords
system
variable set to 1 to force the server to generate short
password hashes instead.
The purpose of the
old_passwords
system variable
is to permit backward compatibility with pre-4.1 clients under
circumstances where the server would otherwise generate long
password hashes. The option does not affect authentication (4.1
and later clients can still use accounts that have long password
hashes), but it does prevent creation of a long password hash in
the user
table as the result of a
password-changing operation. Were that permitted to occur, the
account could no longer be used by pre-4.1 clients. With
old_passwords
disabled, the
following undesirable scenario is possible:
An old pre-4.1 client connects to an account that has a short password hash.
The client changes its own password. With
old_passwords
disabled,
this results in the account having a long password hash.
The next time the old client attempts to connect to the account, it cannot, because the account has a long password hash that requires the 4.1 hashing method during authentication. (Once an account has a long password hash in the user table, only 4.1 and later clients can authenticate for it because pre-4.1 clients do not understand long hashes.)
This scenario illustrates that, if you must support older
pre-4.1 clients, it is problematic to run a 4.1 or newer server
without old_passwords
set to 1.
By running the server with
old_passwords=1
,
password-changing operations do not generate long password
hashes and thus do not cause accounts to become inaccessible to
older clients. (Those clients cannot inadvertently lock
themselves out by changing their password and ending up with a
long password hash.)
The downside of old_passwords=1
is that any passwords created or changed use short hashes, even
for 4.1 or later clients. Thus, you lose the additional security
provided by long password hashes. To create an account that has
a long hash (for example, for use by 4.1 clients) or to change
an existing account to use a long password hash, an
administrator can set the session value of
old_passwords
set to 0 while
leaving the global value set to 1:
mysql>SET @@session.old_passwords = 0;
Query OK, 0 rows affected (0.00 sec) mysql>SELECT @@session.old_passwords, @@global.old_passwords;
+-------------------------+------------------------+ | @@session.old_passwords | @@global.old_passwords | +-------------------------+------------------------+ | 0 | 1 | +-------------------------+------------------------+ 1 row in set (0.00 sec) mysql>CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'newpass';
Query OK, 0 rows affected (0.03 sec) mysql>SET PASSWORD FOR 'existinguser'@'localhost' = PASSWORD('existingpass');
Query OK, 0 rows affected (0.00 sec)
The following scenarios are possible in MySQL 4.1 or later. The
factors are whether the Password
column is
short or long, and, if long, whether the server is started with
old_passwords
enabled or
disabled.
Scenario 1: Short
Password
column in user table:
Only short hashes can be stored in the
Password
column.
The server uses only short hashes during client authentication.
For connected clients, password hash-generating operations
involving the PASSWORD()
function or password-generating statements use short hashes
exclusively. Any change to an account's password results in
that account having a short password hash.
The value of old_passwords
is irrelevant because with a short
Password
column, the server generates
only short password hashes anyway.
This scenario occurs when a pre-4.1 MySQL installation has been
upgraded to 4.1 or later but mysql_upgrade
has not been run to upgrade the system tables in the
mysql
database. (This is not a recommended
configuration because it does not permit use of more secure 4.1
password hashing.)
Scenario 2: Long
Password
column; server started with
old_passwords=1
:
Short or long hashes can be stored in the
Password
column.
4.1 and later clients can authenticate for accounts that have short or long hashes.
Pre-4.1 clients can authenticate only for accounts that have short hashes.
For connected clients, password hash-generating operations
involving the PASSWORD()
function or password-generating statements use short hashes
exclusively. Any change to an account's password results in
that account having a short password hash.
In this scenario, newly created accounts have short password
hashes because old_passwords=1
prevents generation of long hashes. Also, if you create an
account with a long hash before setting
old_passwords
to 1, changing
the account's password while
old_passwords=1
results in the
account being given a short password, causing it to lose the
security benefits of a longer hash.
To create a new account that has a long password hash, or to
change the password of any existing account to use a long hash,
first set the session value of
old_passwords
set to 0 while
leaving the global value set to 1, as described previously.
In this scenario, the server has an up to date
Password
column, but is running with the
default password hashing method set to generate pre-4.1 hash
values. This is not a recommended configuration but may be
useful during a transitional period in which pre-4.1 clients and
passwords are upgraded to 4.1 or later. When that has been done,
it is preferable to run the server with
old_passwords=0
and
secure_auth=1
.
Scenario 3: Long
Password
column; server started with
old_passwords=0
:
Short or long hashes can be stored in the
Password
column.
4.1 and later clients can authenticate using accounts that have short or long hashes.
Pre-4.1 clients can authenticate only using accounts that have short hashes.
For connected clients, password hash-generating operations
involving the PASSWORD()
function or password-generating statements use long hashes
exclusively. A change to an account's password results in
that account having a long password hash.
As indicated earlier, a danger in this scenario is that it is
possible for accounts that have a short password hash to become
inaccessible to pre-4.1 clients. A change to such an account's
password made using the
PASSWORD()
function or a
password-generating statement results in the account being given
a long password hash. From that point on, no pre-4.1 client can
connect to the server using that account. The client must
upgrade to 4.1 or later.
If this is a problem, you can change a password in a special
way. For example, normally you use SET
PASSWORD
as follows to change an account password:
SET PASSWORD FOR 'some_user
'@'some_host
' = PASSWORD('mypass');
To change the password but create a short hash, use the
OLD_PASSWORD()
function instead:
SET PASSWORD FOR 'some_user
'@'some_host
' = OLD_PASSWORD('mypass');
OLD_PASSWORD()
is useful for
situations in which you explicitly want to generate a short
hash.
The disadvantages for each of the preceding scenarios may be summarized as follows:
In scenario 1, you cannot take advantage of longer hashes that provide more secure authentication.
In scenario 2, old_passwords=1
prevents accounts with short hashes from becoming inaccessible,
but password-changing operations cause accounts with long hashes
to revert to short hashes unless you take care to change the
session value of old_passwords
to 0 first.
In scenario 3, accounts with short hashes become inaccessible to
pre-4.1 clients if you change their passwords without explicitly
using OLD_PASSWORD()
.
The best way to avoid compatibility problems related to short password hashes is to not use them:
Upgrade all client programs to MySQL 4.1 or later.
Run the server with
old_passwords=0
.
Reset the password for any account with a short password hash to use a long password hash.
For additional security, run the server with
secure_auth=1
.
When you connect to a MySQL server, you should use a password. The password is not transmitted in clear text over the connection. Password handling during the client connection sequence was upgraded in MySQL 4.1.1 to be very secure. If you are still using pre-4.1.1-style passwords, the encryption algorithm is not as strong as the newer algorithm. With some effort, a clever attacker who can sniff the traffic between the client and the server can crack the password. (See Section 6.1.2.4, “Password Hashing in MySQL”, for a discussion of the different password handling methods.)
All other information is transferred as text, and can be read by anyone who is able to watch the connection. If the connection between the client and the server goes through an untrusted network, and you are concerned about this, you can use the compressed protocol to make traffic much more difficult to decipher. You can also use MySQL's internal SSL support to make the connection even more secure. See Section 6.3.11, “Using Secure Connections”. Alternatively, use SSH to get an encrypted TCP/IP connection between a MySQL server and a MySQL client. You can find an Open Source SSH client at http://www.openssh.org/, and a comparison of both Open Source and Commercial SSH clients at http://en.wikipedia.org/wiki/Comparison_of_SSH_clients.
To make a MySQL system secure, you should strongly consider the following suggestions:
Require all MySQL accounts to have a password. A client
program does not necessarily know the identity of the person
running it. It is common for client/server applications that
the user can specify any user name to the client program. For
example, anyone can use the mysql program
to connect as any other person simply by invoking it as
mysql -u
if
other_user
db_name
other_user
has no password. If all
accounts have a password, connecting using another user's
account becomes much more difficult.
For a discussion of methods for setting passwords, see Section 6.3.5, “Assigning Account Passwords”.
Make sure that the only Unix user account with read or write privileges in the database directories is the account that is used for running mysqld.
Never run the MySQL server as the Unix root
user. This is extremely dangerous, because any user with the
FILE
privilege is able to cause
the server to create files as root
(for
example, ~root/.bashrc
). To prevent this,
mysqld refuses to run as
root
unless that is specified explicitly
using the --user=root
option.
mysqld can (and should) be run as an
ordinary, unprivileged user instead. You can create a separate
Unix account named mysql
to make everything
even more secure. Use this account only for administering
MySQL. To start mysqld as a different Unix
user, add a user
option that specifies the
user name in the [mysqld]
group of the
my.cnf
option file where you specify
server options. For example:
[mysqld] user=mysql
This causes the server to start as the designated user whether you start it manually or by using mysqld_safe or mysql.server. For more details, see Section 6.1.5, “How to Run MySQL as a Normal User”.
Running mysqld as a Unix user other than
root
does not mean that you need to change
the root
user name in the
user
table. User names for MySQL
accounts have nothing to do with user names for Unix
accounts.
Do not grant the FILE
privilege
to nonadministrative users. Any user that has this privilege
can write a file anywhere in the file system with the
privileges of the mysqld daemon. This
includes the server's data directory containing the files that
implement the privilege tables. To make
FILE
-privilege operations a bit
safer, files generated with
SELECT ... INTO
OUTFILE
do not overwrite existing files and are
writable by everyone.
The FILE
privilege may also be
used to read any file that is world-readable or accessible to
the Unix user that the server runs as. With this privilege,
you can read any file into a database table. This could be
abused, for example, by using LOAD
DATA
to load /etc/passwd
into a
table, which then can be displayed with
SELECT
.
To limit the location in which files can be read and written,
set the secure_file_priv
system to a specific directory. See
Section 5.1.4, “Server System Variables”.
Do not grant the PROCESS
or
SUPER
privilege to
nonadministrative users. The output of mysqladmin
processlist and SHOW
PROCESSLIST
shows the text of any statements
currently being executed, so any user who is permitted to see
the server process list might be able to see statements issued
by other users such as UPDATE user SET
password=PASSWORD('not_secure')
.
mysqld reserves an extra connection for
users who have the SUPER
privilege, so that a MySQL root
user can
log in and check server activity even if all normal
connections are in use.
The SUPER
privilege can be used
to terminate client connections, change server operation by
changing the value of system variables, and control
replication servers.
Do not permit the use of symlinks to tables. (This capability
can be disabled with the
--skip-symbolic-links
option.) This is especially important if you run
mysqld as root
, because
anyone that has write access to the server's data directory
then could delete any file in the system! See
Section 8.12.4.2, “Using Symbolic Links for MyISAM Tables on Unix”.
Stored programs and views should be written using the security guidelines discussed in Section 20.6, “Access Control for Stored Programs and Views”.
If you do not trust your DNS, you should use IP addresses rather than host names in the grant tables. In any case, you should be very careful about creating grant table entries using host name values that contain wildcards.
If you want to restrict the number of connections permitted to
a single account, you can do so by setting the
max_user_connections
variable
in mysqld. The
GRANT
statement also supports
resource control options for limiting the extent of server use
permitted to an account. See Section 13.7.1.4, “GRANT Syntax”.
If the plugin directory is writable by the server, it may be
possible for a user to write executable code to a file in the
directory using SELECT
... INTO DUMPFILE
. This can be prevented by making
plugin_dir
read only to the
server or by setting
--secure-file-priv
to a
directory where SELECT
writes
can be made safely.
The following table shows mysqld options and system variables that affect security. For descriptions of each of these, see Section 5.1.3, “Server Command Options”, and Section 5.1.4, “Server System Variables”.
Table 6.1 Security Option/Variable Summary
Name | Cmd-Line | Option File | System Var | Status Var | Var Scope | Dynamic |
---|---|---|---|---|---|---|
allow-suspicious-udfs | Yes | Yes | ||||
automatic_sp_privileges | Yes | Global | Yes | |||
chroot | Yes | Yes | ||||
des-key-file | Yes | Yes | ||||
local_infile | Yes | Global | Yes | |||
old_passwords | Yes | Both | Yes | |||
safe-user-create | Yes | Yes | ||||
secure-auth | Yes | Yes | Global | Yes | ||
- Variable: secure_auth | Yes | Global | Yes | |||
secure-file-priv | Yes | Yes | Global | No | ||
- Variable: secure_file_priv | Yes | Global | No | |||
skip-grant-tables | Yes | Yes | ||||
skip-name-resolve | Yes | Yes | Global | No | ||
- Variable: skip_name_resolve | Yes | Global | No | |||
skip-networking | Yes | Yes | Global | No | ||
- Variable: skip_networking | Yes | Global | No | |||
skip-show-database | Yes | Yes | Global | No | ||
- Variable: skip_show_database | Yes | Global | No |
On Windows, you can run the server as a Windows service using a normal user account.
On Unix, the MySQL server mysqld can be started
and run by any user. However, you should avoid running the server
as the Unix root
user for security reasons. To
change mysqld to run as a normal unprivileged
Unix user user_name
, you must do the
following:
Stop the server if it is running (use mysqladmin shutdown).
Change the database directories and files so that
user_name
has privileges to read
and write files in them (you might need to do this as the Unix
root
user):
shell> chown -R user_name
/path/to/mysql/datadir
If you do not do this, the server will not be able to access
databases or tables when it runs as
user_name
.
If directories or files within the MySQL data directory are
symbolic links, chown -R
might not follow
symbolic links for you. If it does not, you will also need to
follow those links and change the directories and files they
point to.
Start the server as user user_name
.
Another alternative is to start mysqld as
the Unix root
user and use the
--user=
option. mysqld starts up, then switches to
run as the Unix user user_name
user_name
before accepting any connections.
To start the server as the given user automatically at system
startup time, specify the user name by adding a
user
option to the
[mysqld]
group of the
/etc/my.cnf
option file or the
my.cnf
option file in the server's data
directory. For example:
[mysqld]
user=user_name
If your Unix machine itself is not secured, you should assign
passwords to the MySQL root
account in the
grant tables. Otherwise, any user with a login account on that
machine can run the mysql client with a
--user=root
option and perform any
operation. (It is a good idea to assign passwords to MySQL
accounts in any case, but especially so when other login accounts
exist on the server host.) See
Section 2.10.4, “Securing the Initial MySQL Accounts”.
The LOAD DATA
statement can load a
file that is located on the server host, or it can load a file
that is located on the client host when the
LOCAL
keyword is specified.
There are two potential security issues with supporting the
LOCAL
version of LOAD
DATA
statements:
The transfer of the file from the client host to the server
host is initiated by the MySQL server. In theory, a patched
server could be built that would tell the client program to
transfer a file of the server's choosing rather than the file
named by the client in the LOAD
DATA
statement. Such a server could access any file
on the client host to which the client user has read access.
In a Web environment where the clients are connecting from a
Web server, a user could use
LOAD DATA
LOCAL
to read any files that the Web server process
has read access to (assuming that a user could run any command
against the SQL server). In this environment, the client with
respect to the MySQL server actually is the Web server, not
the remote program being run by the user who connects to the
Web server.
To deal with these problems,
LOAD DATA
LOCAL
works like this:
By default, all MySQL clients and libraries in binary
distributions are compiled with the
-DENABLED_LOCAL_INFILE=1
option.
If you build MySQL from source but do not invoke
CMake with the
-DENABLED_LOCAL_INFILE=1
option,
LOAD DATA
LOCAL
cannot be used by any client unless it is
written explicitly to invoke
mysql_options(...
MYSQL_OPT_LOCAL_INFILE, 0)
. See
Section 24.8.7.50, “mysql_options()”.
You can disable all
LOAD DATA
LOCAL
statements from the server side by starting
mysqld with the
--local-infile=0
option.
For the mysql command-line client, enable
LOAD DATA
LOCAL
by specifying the
--local-infile[=1]
option, or
disable it with the
--local-infile=0
option. For
mysqlimport, local data file loading is off
by default; enable it with the
--local
or
-L
option. In any case, successful use of a
local load operation requires that the server permits it.
If you use LOAD
DATA LOCAL
in Perl scripts or other programs that
read the [client]
group from option files,
you can add the local-infile=1
option to
that group. However, to keep this from causing problems for
programs that do not understand
local-infile
, specify it using the
loose-
prefix:
[client] loose-local-infile=1
If LOAD DATA
LOCAL
is disabled, either in the server or the
client, a client that attempts to issue such a statement
receives the following error message:
ERROR 1148: The used command is not allowed with this MySQL version
Applications that access MySQL should not trust any data entered
by users, who can try to trick your code by entering special or
escaped character sequences in Web forms, URLs, or whatever
application you have built. Be sure that your application remains
secure if a user enters something like “; DROP
DATABASE mysql;
”. This is an extreme example, but
large security leaks and data loss might occur as a result of
hackers using similar techniques, if you do not prepare for them.
A common mistake is to protect only string data values. Remember
to check numeric data as well. If an application generates a query
such as SELECT * FROM table WHERE ID=234
when a
user enters the value 234
, the user can enter
the value 234 OR 1=1
to cause the application
to generate the query SELECT * FROM table WHERE ID=234 OR
1=1
. As a result, the server retrieves every row in the
table. This exposes every row and causes excessive server load.
The simplest way to protect from this type of attack is to use
single quotation marks around the numeric constants:
SELECT * FROM table WHERE ID='234'
. If the user
enters extra information, it all becomes part of the string. In a
numeric context, MySQL automatically converts this string to a
number and strips any trailing nonnumeric characters from it.
Sometimes people think that if a database contains only publicly available data, it need not be protected. This is incorrect. Even if it is permissible to display any row in the database, you should still protect against denial of service attacks (for example, those that are based on the technique in the preceding paragraph that causes the server to waste resources). Otherwise, your server becomes unresponsive to legitimate users.
Checklist:
Enable strict SQL mode to tell the server to be more restrictive of what data values it accepts. See Section 5.1.7, “Server SQL Modes”.
Try to enter single and double quotation marks
(“'
” and
“"
”) in all of your Web forms.
If you get any kind of MySQL error, investigate the problem
right away.
Try to modify dynamic URLs by adding %22
(“"
”), %23
(“#
”), and
%27
(“'
”)
to them.
Try to modify data types in dynamic URLs from numeric to character types using the characters shown in the previous examples. Your application should be safe against these and similar attacks.
Try to enter characters, spaces, and special symbols rather than numbers in numeric fields. Your application should remove them before passing them to MySQL or else generate an error. Passing unchecked values to MySQL is very dangerous!
Check the size of data before passing it to MySQL.
Have your application connect to the database using a user name different from the one you use for administrative purposes. Do not give your applications any access privileges they do not need.
Many application programming interfaces provide a means of escaping special characters in data values. Properly used, this prevents application users from entering values that cause the application to generate statements that have a different effect than you intend:
MySQL C API: Use the
mysql_real_escape_string()
API
call.
MySQL++: Use the escape
and
quote
modifiers for query streams.
PHP: Use either the mysqli
or
pdo_mysql
extensions, and not the older
ext/mysql
extension. The preferred API's
support the improved MySQL authentication protocol and
passwords, as well as prepared statements with placeholders.
See also Choosing an API.
If the older ext/mysql
extension must be
used, then for escaping use the
mysql_real_escape_string()
function and not
mysql_escape_string()
or
addslashes()
because only
mysql_real_escape_string()
is
character set-aware; the other functions can be
“bypassed” when using (invalid) multibyte
character sets.
Perl DBI: Use placeholders or the quote()
method.
Ruby DBI: Use placeholders or the quote()
method.
Java JDBC: Use a PreparedStatement
object
and placeholders.
Other programming interfaces might have similar capabilities.
The primary function of the MySQL privilege system is to
authenticate a user who connects from a given host and to associate
that user with privileges on a database such as
SELECT
,
INSERT
,
UPDATE
, and
DELETE
. Additional functionality
includes the ability to have anonymous users and to grant privileges
for MySQL-specific functions such as
LOAD DATA
INFILE
and administrative operations.
There are some things that you cannot do with the MySQL privilege system:
You cannot explicitly specify that a given user should be denied access. That is, you cannot explicitly match a user and then refuse the connection.
You cannot specify that a user has privileges to create or drop tables in a database but not to create or drop the database itself.
A password applies globally to an account. You cannot associate a password with a specific object such as a database, table, or routine.
The user interface to the MySQL privilege system consists of SQL
statements such as CREATE USER
,
GRANT
, and
REVOKE
. See
Section 13.7.1, “Account Management Statements”.
Internally, the server stores privilege information in the grant
tables of the mysql
database (that is, in the
database named mysql
). The MySQL server reads the
contents of these tables into memory when it starts and bases
access-control decisions on the in-memory copies of the grant
tables.
The MySQL privilege system ensures that all users may perform only the operations permitted to them. As a user, when you connect to a MySQL server, your identity is determined by the host from which you connect and the user name you specify. When you issue requests after connecting, the system grants privileges according to your identity and what you want to do.
MySQL considers both your host name and user name in identifying you
because there is no reason to assume that a given user name belongs
to the same person on all hosts. For example, the user
joe
who connects from
office.example.com
need not be the same person as
the user joe
who connects from
home.example.com
. MySQL handles this by enabling
you to distinguish users on different hosts that happen to have the
same name: You can grant one set of privileges for connections by
joe
from office.example.com
,
and a different set of privileges for connections by
joe
from home.example.com
. To
see what privileges a given account has, use the
SHOW GRANTS
statement. For example:
SHOW GRANTS FOR 'joe'@'office.example.com'; SHOW GRANTS FOR 'joe'@'home.example.com';
MySQL access control involves two stages when you run a client program that connects to the server:
Stage 1: The server accepts or rejects the connection based on your identity and whether you can verify your identity by supplying the correct password.
Stage 2: Assuming that you can
connect, the server checks each statement you issue to determine
whether you have sufficient privileges to perform it. For example,
if you try to select rows from a table in a database or drop a table
from the database, the server verifies that you have the
SELECT
privilege for the table or the
DROP
privilege for the database.
For a more detailed description of what happens during each stage, see Section 6.2.4, “Access Control, Stage 1: Connection Verification”, and Section 6.2.5, “Access Control, Stage 2: Request Verification”.
If your privileges are changed (either by yourself or someone else) while you are connected, those changes do not necessarily take effect immediately for the next statement that you issue. For details about the conditions under which the server reloads the grant tables, see Section 6.2.6, “When Privilege Changes Take Effect”.
For general security-related advice, see Section 6.1, “General Security Issues”. For help in diagnosing privilege-related problems, see Section 6.2.7, “Troubleshooting Problems Connecting to MySQL”.
MySQL provides privileges that apply in different contexts and at different levels of operation:
Administrative privileges enable users to manage operation of the MySQL server. These privileges are global because they are not specific to a particular database.
Database privileges apply to a database and to all objects within it. These privileges can be granted for specific databases, or globally so that they apply to all databases.
Privileges for database objects such as tables, indexes, views, and stored routines can be granted for specific objects within a database, for all objects of a given type within a database (for example, all tables in a database), or globally for all objects of a given type in all databases).
Information about account privileges is stored in the
user
, db
,
tables_priv
, columns_priv
,
and procs_priv
tables in the
mysql
database (see
Section 6.2.2, “Privilege System Grant Tables”). The MySQL server reads
the contents of these tables into memory when it starts and
reloads them under the circumstances indicated in
Section 6.2.6, “When Privilege Changes Take Effect”. Access-control decisions are
based on the in-memory copies of the grant tables.
Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges or features. To make sure that you can take advantage of any new capabilities, update your grant tables to have the current structure whenever you update to a new version of MySQL. See Section 4.4.7, “mysql_upgrade — Check and Upgrade MySQL Tables”.
The following table shows the privilege names used at the SQL
level in the GRANT
and
REVOKE
statements, along with the
column name associated with each privilege in the grant tables and
the context in which the privilege applies.
Table 6.2 Permissible Privileges for GRANT and REVOKE
Privilege | Column | Context |
---|---|---|
CREATE | Create_priv | databases, tables, or indexes |
DROP | Drop_priv | databases, tables, or views |
GRANT OPTION | Grant_priv | databases, tables, or stored routines |
LOCK TABLES | Lock_tables_priv | databases |
REFERENCES | References_priv | databases or tables |
EVENT | Event_priv | databases |
ALTER | Alter_priv | tables |
DELETE | Delete_priv | tables |
INDEX | Index_priv | tables |
INSERT | Insert_priv | tables or columns |
SELECT | Select_priv | tables or columns |
UPDATE | Update_priv | tables or columns |
CREATE TEMPORARY TABLES | Create_tmp_table_priv | tables |
TRIGGER | Trigger_priv | tables |
CREATE VIEW | Create_view_priv | views |
SHOW VIEW | Show_view_priv | views |
ALTER ROUTINE | Alter_routine_priv | stored routines |
CREATE ROUTINE | Create_routine_priv | stored routines |
EXECUTE | Execute_priv | stored routines |
FILE | File_priv | file access on server host |
CREATE TABLESPACE | Create_tablespace_priv | server administration |
CREATE USER | Create_user_priv | server administration |
PROCESS | Process_priv | server administration |
PROXY | see proxies_priv table | server administration |
RELOAD | Reload_priv | server administration |
REPLICATION CLIENT | Repl_client_priv | server administration |
REPLICATION SLAVE | Repl_slave_priv | server administration |
SHOW DATABASES | Show_db_priv | server administration |
SHUTDOWN | Shutdown_priv | server administration |
SUPER | Super_priv | server administration |
ALL [PRIVILEGES] | server administration | |
USAGE | server administration |
The following list provides a general description of each privilege available in MySQL. Particular SQL statements might have more specific privilege requirements than indicated here. If so, the description for the statement in question provides the details.
The ALL
or
ALL PRIVILEGES
privilege specifier is shorthand. It stands for “all
privileges available at a given privilege level”
(except GRANT OPTION
). For
example, granting ALL
at the
global or table level grants all global privileges or all
table-level privileges.
The ALTER
privilege enables use
of ALTER TABLE
to change the
structure of tables. ALTER
TABLE
also requires the
CREATE
and
INSERT
privileges. Renaming a
table requires ALTER
and
DROP
on the old table,
CREATE
, and
INSERT
on the new table.
The ALTER ROUTINE
privilege is
needed to alter or drop stored routines (procedures and
functions).
The CREATE
privilege enables
creation of new databases and tables.
The CREATE ROUTINE
privilege is
needed to create stored routines (procedures and functions).
The CREATE TABLESPACE
privilege
is needed to create, alter, or drop tablespaces and log file
groups.
The CREATE TEMPORARY TABLES
privilege enables the creation of temporary tables using the
CREATE TEMPORARY
TABLE
statement.
After a session has created a temporary table, the server
performs no further privilege checks on the table. The
creating session can perform any operation on the table, such
as DROP TABLE
,
INSERT
,
UPDATE
, or
SELECT
.
One implication of this behavior is that a session can
manipulate its temporary tables even if the current user has
no privilege to create them. Suppose that the current user
does not have the CREATE TEMPORARY
TABLES
privilege but is able to execute a
DEFINER
-context stored procedure that
executes with the privileges of a user who does have
CREATE TEMPORARY TABLES
and
that creates a temporary table. While the procedure executes,
the session uses the privileges of the defining user. After
the procedure returns, the effective privileges revert to
those of the current user, which can still see the temporary
table and perform any operation on it.
To keep privileges for temporary and nontemporary tables
separate, a common workaround for this situation is to create
a database dedicated to the use of temporary tables. Then for
that database, a user can be granted the
CREATE TEMPORARY TABLES
privilege, along with any other privileges required for
temporary table operations done by that user.
The CREATE USER
privilege
enables use of ALTER USER
,
CREATE USER
,
DROP USER
,
RENAME USER
, and
REVOKE ALL
PRIVILEGES
.
The CREATE VIEW
privilege
enables use of CREATE VIEW
.
The DELETE
privilege enables
rows to be deleted from tables in a database.
The DROP
privilege enables you
to drop (remove) existing databases, tables, and views. The
DROP
privilege is required in
order to use the statement ALTER TABLE ... DROP
PARTITION
on a partitioned table. The
DROP
privilege is also required
for TRUNCATE TABLE
.
If you grant the DROP
privilege for the mysql
database to a user,
that user can drop the database in which the MySQL access
privileges are stored.
The EVENT
privilege is required
to create, alter, drop, or see events for the Event Scheduler.
The EXECUTE
privilege is
required to execute stored routines (procedures and
functions).
The FILE
privilege gives you
permission to read and write files on the server host using
the LOAD DATA
INFILE
and
SELECT ... INTO
OUTFILE
statements and the
LOAD_FILE()
function. A user
who has the FILE
privilege can
read any file on the server host that is either world-readable
or readable by the MySQL server. (This implies the user can
read any file in any database directory, because the server
can access any of those files.) The
FILE
privilege also enables the
user to create new files in any directory where the MySQL
server has write access. This includes the server's data
directory containing the files that implement the privilege
tables. As a security measure, the server will not overwrite
existing files.
To limit the location in which files can be read and written,
set the secure_file_priv
system to a specific directory. See
Section 5.1.4, “Server System Variables”.
The GRANT OPTION
privilege
enables you to give to other users or remove from other users
those privileges that you yourself possess.
The INDEX
privilege enables you
to create or drop (remove) indexes.
INDEX
applies to existing
tables. If you have the CREATE
privilege for a table, you can include index definitions in
the CREATE TABLE
statement.
The INSERT
privilege enables
rows to be inserted into tables in a database.
INSERT
is also required for the
ANALYZE TABLE
,
OPTIMIZE TABLE
, and
REPAIR TABLE
table-maintenance
statements.
The LOCK TABLES
privilege
enables the use of explicit LOCK
TABLES
statements to lock tables for which you have
the SELECT
privilege. This
includes the use of write locks, which prevents other sessions
from reading the locked table.
The PROCESS
privilege pertains
to display of information about the threads executing within
the server (that is, information about the statements being
executed by sessions). The privilege enables use of
SHOW PROCESSLIST
or
mysqladmin processlist to see threads
belonging to other accounts; you can always see your own
threads. The PROCESS
privilege
also enables use of SHOW
ENGINE
.
The PROXY
privilege enables a
user to impersonate or become known as another user. See
Section 6.3.9, “Proxy Users”.
The REFERENCES
privilege is
unused before MySQL 5.7.6. As of 5.7.6, creation of a foreign
key constraint requires the
REFERENCES
privilege for the
parent table.
The RELOAD
privilege enables
use of the FLUSH
statement. It
also enables mysqladmin commands that are
equivalent to FLUSH
operations:
flush-hosts
, flush-logs
,
flush-privileges
,
flush-status
,
flush-tables
,
flush-threads
, refresh
,
and reload
.
The reload
command tells the server to
reload the grant tables into memory.
flush-privileges
is a synonym for
reload
. The refresh
command closes and reopens the log files and flushes all
tables. The other
flush-
commands perform functions similar to
xxx
refresh
, but are more specific and may be
preferable in some instances. For example, if you want to
flush just the log files, flush-logs
is a
better choice than refresh
.
The REPLICATION CLIENT
privilege enables the use of SHOW MASTER
STATUS
, SHOW SLAVE
STATUS
, and SHOW BINARY
LOGS
.
The REPLICATION SLAVE
privilege
should be granted to accounts that are used by slave servers
to connect to the current server as their master. Without this
privilege, the slave cannot request updates that have been
made to databases on the master server.
The SELECT
privilege enables
you to select rows from tables in a database.
SELECT
statements require the
SELECT
privilege only if they
actually retrieve rows from a table. Some
SELECT
statements do not access
tables and can be executed without permission for any
database. For example, you can use
SELECT
as a simple calculator
to evaluate expressions that make no reference to tables:
SELECT 1+1; SELECT PI()*2;
The SELECT
privilege is also
needed for other statements that read column values. For
example, SELECT
is needed for
columns referenced on the right hand side of
col_name
=expr
assignment in UPDATE
statements
or for columns named in the WHERE
clause of
DELETE
or
UPDATE
statements.
The SHOW DATABASES
privilege
enables the account to see database names by issuing the
SHOW DATABASE
statement. Accounts that do
not have this privilege see only databases for which they have
some privileges, and cannot use the statement at all if the
server was started with the
--skip-show-database
option.
Note that any global privilege is a
privilege for the database.
The SHOW VIEW
privilege enables
use of SHOW CREATE VIEW
.
The SHUTDOWN
privilege enables
use of the SHUTDOWN
statement,
the mysqladmin shutdown command, and the
mysql_shutdown()
C API
function.
The SUPER
privilege enables an
account to use CHANGE MASTER
TO
, KILL
or
mysqladmin kill to kill threads belonging
to other accounts (you can always kill your own threads),
PURGE BINARY LOGS
,
configuration changes using
SET
GLOBAL
to modify global system variables, the
mysqladmin debug command, enabling or
disabling logging, performing updates even if the
read_only
system variable is
enabled, starting and stopping replication on slave servers,
specification of any account in the DEFINER
attribute of stored programs and views, and enables you to
connect (once) even if the connection limit controlled by the
max_connections
system
variable is reached.
To create or alter stored functions if binary logging is
enabled, you may also need the
SUPER
privilege, as described
in Section 20.7, “Binary Logging of Stored Programs”.
The TRIGGER
privilege enables
trigger operations. You must have this privilege for a table
to create, drop, execute, or display triggers for that table.
When a trigger is activated (by a user who has privileges to
execute INSERT
,
UPDATE
, or
DELETE
statements for the table
associated with the trigger), trigger execution requires that
the user who defined the trigger still have the
TRIGGER
privilege.
The UPDATE
privilege enables
rows to be updated in tables in a database.
The USAGE
privilege specifier
stands for “no privileges.” It is used at the
global level with GRANT
to
modify account attributes such as resource limits or SSL
characteristics without affecting existing account privileges.
It is a good idea to grant to an account only those privileges
that it needs. You should exercise particular caution in granting
the FILE
and administrative
privileges:
The FILE
privilege can be
abused to read into a database table any files that the MySQL
server can read on the server host. This includes all
world-readable files and files in the server's data directory.
The table can then be accessed using
SELECT
to transfer its contents
to the client host.
The GRANT OPTION
privilege
enables users to give their privileges to other users. Two
users that have different privileges and with the
GRANT OPTION
privilege are able
to combine privileges.
The ALTER
privilege may be used
to subvert the privilege system by renaming tables.
The SHUTDOWN
privilege can be
abused to deny service to other users entirely by terminating
the server.
The PROCESS
privilege can be
used to view the plain text of currently executing statements,
including statements that set or change passwords.
The SUPER
privilege can be used
to terminate other sessions or change how the server operates.
Privileges granted for the mysql
database
itself can be used to change passwords and other access
privilege information. Passwords are stored encrypted, so a
malicious user cannot simply read them to know the plain text
password. However, a user with write access to the
user
table Password
column can change an account's password, and then connect to
the MySQL server using that account.
The mysql
system database includes several
grant tables that contain information about user accounts and the
privileges held by them.
Normally, to manipulate the contents of grant tables, you modify
them indirectly by using account-management statements such as
CREATE USER
,
GRANT
, and
REVOKE
to set up accounts and
control the privileges available to each one. See
Section 13.7.1, “Account Management Statements”. The discussion here
describes the underlying structure of the grant tables and how the
server uses their contents when interacting with clients.
Direct modification of grant tables using statements such as
INSERT
,
UPDATE
, or
DELETE
is discouraged. The server
is free to ignore rows that become malformed as a result of such
modifications.
These mysql
database tables contain grant
information:
Other tables in the mysql
database do not hold
grant information and are discussed elsewhere:
engine_cost
,
server_cost
: Optimizer cost estimates. See
Section 8.9.5, “The Optimizer Cost Model”.
event
: Information about Event Scheduler
events. See Section 20.4, “Using the Event Scheduler”.
func
: Information about user-defined
functions. See Section 25.4, “Adding New Functions to MySQL”.
general_log
, slow_log
:
Used for logging. See Section 5.2, “MySQL Server Logs”.
gtid_executed
: Used for replication. See
mysql.gtid_executed Table.
help_
: Used
for server-side help. See
Section 5.1.10, “Server-Side Help”.
xxx
innodb_index_stats
,
innodb_table_stats
: Used for
InnoDB
persistent optimizer statistics. See
Section 14.4.11.1, “Configuring Persistent Optimizer Statistics Parameters”.
ndb_binlog_index
: Used for MySQL Cluster
replication. See
Section 18.6.4, “MySQL Cluster Replication Schema and Tables”.
plugin
: Information about server plugins.
See Section 5.1.8.1, “Installing and Uninstalling Plugins”, and
Section 25.2, “The MySQL Plugin API”.
proc
: Information about stored procedures
and functions. See Section 20.2, “Using Stored Routines (Procedures and Functions)”.
servers
: Used by the
FEDERATED
storage engine. See
Section 15.8.2.2, “Creating a FEDERATED Table Using CREATE SERVER”.
slave_master_info
,
slave_relay_log_info
,
slave_worker_info
: Used for replication.
See Section 17.2.4, “Replication Relay and Status Logs”.
time_zone_
:
Used for time zone information. See
Section 10.6, “MySQL Server Time Zone Support”.
xxx
Each grant table contains scope columns and privilege columns:
Scope columns determine the scope of each row in the tables;
that is, the context in which the row applies. For example, a
user
table row with Host
and User
values of
'thomas.loc.gov'
and
'bob'
applies to authenticating connections
made to the server from the host
thomas.loc.gov
by a client that specifies a
user name of bob
. Similarly, a
db
table row with Host
,
User
, and Db
column
values of 'thomas.loc.gov'
,
'bob'
and 'reports'
applies when bob
connects from the host
thomas.loc.gov
to access the
reports
database. The
tables_priv
and
columns_priv
tables contain scope columns
indicating tables or table/column combinations to which each
row applies. The procs_priv
scope columns
indicate the stored routine to which each row applies.
Privilege columns indicate which privileges a table row grants; that is, which operations it permits to be performed. The server combines the information in the various grant tables to form a complete description of a user's privileges. Section 6.2.5, “Access Control, Stage 2: Request Verification”, describes the rules for this.
The server uses the grant tables in the following manner:
The user
table scope columns determine
whether to reject or permit incoming connections. For
permitted connections, any privileges granted in the
user
table indicate the user's global
privileges. Any privileges granted in this table apply to
all databases on the server.
Because any global privilege is considered a privilege for
all databases, any global privilege enables a user to see
all database names with SHOW
DATABASES
or by examining the
SCHEMATA
table of
INFORMATION_SCHEMA
.
The db
table scope columns determine which
users can access which databases from which hosts. The
privilege columns determine the permitted operations. A
privilege granted at the database level applies to the
database and to all objects in the database, such as tables
and stored programs.
The tables_priv
and
columns_priv
tables are similar to the
db
table, but are more fine-grained: They
apply at the table and column levels rather than at the
database level. A privilege granted at the table level applies
to the table and to all its columns. A privilege granted at
the column level applies only to a specific column.
The procs_priv
table applies to stored
routines (procedures and functions). A privilege granted at
the routine level applies only to a single procedure or
function.
The proxies_priv
table indicates which
users can act as proxies for other users and whether a user
can grant the PROXY
privilege
to other users.
The server uses the user
and
db
tables in the mysql
database at both the first and second stages of access control
(see Section 6.2, “The MySQL Access Privilege System”). The columns in the
user
and db
tables are shown
here.
Table 6.3 user and db Table Columns
Table Name | user | db |
---|---|---|
Scope columns | Host | Host |
User | Db | |
Password | User | |
Privilege columns | Select_priv | Select_priv |
Insert_priv | Insert_priv | |
Update_priv | Update_priv | |
Delete_priv | Delete_priv | |
Index_priv | Index_priv | |
Alter_priv | Alter_priv | |
Create_priv | Create_priv | |
Drop_priv | Drop_priv | |
Grant_priv | Grant_priv | |
Create_view_priv | Create_view_priv | |
Show_view_priv | Show_view_priv | |
Create_routine_priv | Create_routine_priv | |
Alter_routine_priv | Alter_routine_priv | |
Execute_priv | Execute_priv | |
Trigger_priv | Trigger_priv | |
Event_priv | Event_priv | |
Create_tmp_table_priv | Create_tmp_table_priv | |
Lock_tables_priv | Lock_tables_priv | |
References_priv | References_priv | |
Reload_priv | ||
Shutdown_priv | ||
Process_priv | ||
File_priv | ||
Show_db_priv | ||
Super_priv | ||
Repl_slave_priv | ||
Repl_client_priv | ||
Create_user_priv | ||
Create_tablespace_priv | ||
Security columns | ssl_type | |
ssl_cipher | ||
x509_issuer | ||
x509_subject | ||
plugin | ||
authentication_string | ||
password_expired | ||
password_last_changed | ||
password_lifetime | ||
account_locked | ||
Resource control columns | max_questions | |
max_updates | ||
max_connections | ||
max_user_connections |
The user
table plugin
,
Password
, and
authentication_string
columns store
authentication plugin and credential information. In MySQL 5.7.6,
the Password
column was removed and all
credentials are stored in the
authentication_string
column.
If an account row names a plugin in the plugin
column, the server uses it to authenticate connection attempts for
the account. It is up to the plugin whether it uses the
Password
and
authentication_string
column values.
As of MySQL 5.7.2, the plugin
column must be
nonempty.
Before MySQL 5.7.2, the plugin
column for an
account row is permitted to be empty. In this case, the server
authenticates the account using the
mysql_native_password
or
mysql_old_password
plugin implicitly, depending
on the format of the password hash in the
Password
column. If the
Password
value is empty or a 4.1 password hash
(41 characters), the server uses
mysql_native_password
. If the password value is
a pre-4.1 password hash (16 characters), the server uses
mysql_old_password
. (For additional information
about these hash formats, see Section 6.1.2.4, “Password Hashing in MySQL”.)
Clients must match the password in the Password
column of the account row.
At startup, and at runtime when
FLUSH PRIVILEGES
is executed, the server checks user
table rows.
As of MySQL 5.7.2, for any row with an empty
plugin
column, the server writes a warning to
the error log of this form:
[Warning] User entry 'user_name
'@'host_name
' has an empty plugin value. The user will be ignored and no one can login with this user anymore.
To address this problem, see Section 6.4.1.3, “Migrating Away from Pre-4.1 Password Hashing and the mysql_old_password Plugin”.
The password_expired
column permits DBAs to
expire account passwords and require users to reset their
password. The default password_expired
value is
'N'
, but can be set to 'Y'
with the ALTER USER
statement.
After an account's password has been expired, all operations
performed by the account in subsequent connections to the server
result in an error until the user issues an
ALTER USER
statement (for MySQL
5.7.6 and up) or SET PASSWORD
statement (before MySQL 5.7.6) to establish a new account
password.
It is possible after password expiration to “reset” a password by setting it to its current value. As a matter of good policy, it is preferable to choose a different password.
password_last_changed
(added in MySQL 5.7.4) is
a TIMESTAMP
column indicating when the password
was last changed. The value is non-NULL
only
for accounts that use MySQL built-in authentication methods
(accounts that use an authentication plugin of
mysql_native_password
,
mysql_old_password
, or
sha256_password
). The value is
NULL
for other accounts, such as those
authenticated using an external authentication system.
password_last_changed
is updated by the
CREATE USER
,
ALTER USER
, and
SET PASSWORD
statements, and by
GRANT
statements that create an
account or change an account password.
password_lifetime
(added in MySQL 5.7.4)
indicates the account password lifetime, in days. If the password
is past its lifetime (assessed using the
password_last_changed
column), the server
considers the password expired when clients connect using the
account. A value of N
greater than zero
means that the password must be changed every
N
days. A value of 0 disables automatic
password expiration. If the value is NULL
(the
default), the global expiration policy applies, as defined by the
default_password_lifetime
system
variable.
account_locked
(added in MySQL 5.7.6) indicates
whether the account is locked (see
Section 6.3.10, “User Account Locking”).
During the second stage of access control, the server performs
request verification to ensure that each client has sufficient
privileges for each request that it issues. In addition to the
user
and db
grant tables,
the server may also consult the tables_priv
and
columns_priv
tables for requests that involve
tables. The latter tables provide finer privilege control at the
table and column levels. They have the columns shown in the
following table.
Table 6.4 tables_priv and columns_priv Table Columns
Table Name | tables_priv | columns_priv |
---|---|---|
Scope columns | Host | Host |
Db | Db | |
User | User | |
Table_name | Table_name | |
Column_name | ||
Privilege columns | Table_priv | Column_priv |
Column_priv | ||
Other columns | Timestamp | Timestamp |
Grantor |
The Timestamp
and Grantor
columns are set to the current timestamp and the
CURRENT_USER
value, respectively,
but are otherwise unused.
For verification of requests that involve stored routines, the
server may consult the procs_priv
table, which
has the columns shown in the following table.
Table 6.5 procs_priv Table Columns
Table Name | procs_priv |
---|---|
Scope columns | Host |
Db | |
User | |
Routine_name | |
Routine_type | |
Privilege columns | Proc_priv |
Other columns | Timestamp |
Grantor |
The Routine_type
column is an
ENUM
column with values of
'FUNCTION'
or 'PROCEDURE'
to
indicate the type of routine the row refers to. This column
enables privileges to be granted separately for a function and a
procedure with the same name.
The Timestamp
and Grantor
columns are unused.
The proxies_priv
table records information
about proxy accounts. It has these columns:
For an account to be able to grant the
PROXY
privilege to other accounts,
it must have a row in the proxies_priv
table
with With_grant
set to 1 and
Proxied_host
and
Proxied_user
set to indicate the account or
accounts for which the privilege can be granted. For example, the
'root'@'localhost'
account created during MySQL
installation has a row in the proxies_priv
table that enables granting the
PROXY
privilege for
''@''
, that is, for all users and all hosts.
This enables root
to set up proxy users, as
well as to delegate to other accounts the authority to set up
proxy users. See Section 6.3.9, “Proxy Users”.
Scope columns in the grant tables contain strings. The default value for each is the empty string. The following table shows the number of characters permitted in each column.
Table 6.6 Grant Table Scope Column Lengths
Column Name | Maximum Permitted Characters |
---|---|
Host , Proxied_host | 60 |
User , Proxied_user | 32 (16 before MySQL 5.7.8) |
Password | 41 |
Db | 64 |
Table_name | 64 |
Column_name | 64 |
Routine_name | 64 |
For access-checking purposes, comparisons of
User
, Proxied_user
,
Password
, Db
, and
Table_name
values are case sensitive.
Comparisons of Host
,
Proxied_host
, Column_name
,
and Routine_name
values are not case sensitive.
The user
and db
tables list
each privilege in a separate column that is declared as
ENUM('N','Y') DEFAULT 'N'
. In other words, each
privilege can be disabled or enabled, with the default being
disabled.
The tables_priv
,
columns_priv
, and procs_priv
tables declare the privilege columns as
SET
columns. Values in these
columns can contain any combination of the privileges controlled
by the table. Only those privileges listed in the column value are
enabled.
Table 6.7 Set-Type Privilege Column Values
Table Name | Column Name | Possible Set Elements |
---|---|---|
tables_priv | Table_priv | 'Select', 'Insert', 'Update', 'Delete', 'Create', 'Drop',
'Grant', 'References', 'Index', 'Alter', 'Create View',
'Show view', 'Trigger' |
tables_priv | Column_priv | 'Select', 'Insert', 'Update', 'References' |
columns_priv | Column_priv | 'Select', 'Insert', 'Update', 'References' |
procs_priv | Proc_priv | 'Execute', 'Alter Routine', 'Grant' |
Only the user
table specifies administrative
privileges, such as RELOAD
and
SHUTDOWN
. Administrative operations
are operations on the server itself and are not database-specific,
so there is no reason to list these privileges in the other grant
tables. Consequently, the server need consult only the
user
table to determine whether a user can
perform an administrative operation.
The FILE
privilege also is
specified only in the user
table. It is not an
administrative privilege as such, but a user's ability to read or
write files on the server host is independent of the database
being accessed.
The server reads the contents of the grant tables into memory when
it starts. You can tell it to reload the tables by issuing a
FLUSH PRIVILEGES
statement or executing a mysqladmin
flush-privileges or mysqladmin reload
command. Changes to the grant tables take effect as indicated in
Section 6.2.6, “When Privilege Changes Take Effect”.
When you modify an account, it is a good idea to verify that your
changes have the intended effect. To check the privileges for a
given account, use the SHOW GRANTS
statement. For example, to determine the privileges that are
granted to an account with user name and host name values of
bob
and pc84.example.com
,
use this statement:
SHOW GRANTS FOR 'bob'@'pc84.example.com';
To display nonprivilege properties of an account, use
SHOW CREATE USER
:
SHOW CREATE USER 'bob'@'pc84.example.com';
MySQL account names consist of a user name and a host name. This enables creation of accounts for users with the same name who can connect from different hosts. This section describes how to write account names, including special values and wildcard rules.
In SQL statements such as CREATE
USER
, GRANT
, and
SET PASSWORD
, write account names
using the following rules:
Syntax for account names is
'
.
user_name
'@'host_name
'
An account name consisting only of a user name is equivalent
to
'
.
For example, user_name
'@'%''me'
is equivalent to
'me'@'%'
.
The user name and host name need not be quoted if they are
legal as unquoted identifiers. Quotes are necessary to specify
a user_name
string containing
special characters (such as
“-
”), or a
host_name
string containing special
characters or wildcard characters (such as
“%
”); for example,
'test-user'@'%.com'
.
Quote user names and host names as identifiers or as strings,
using either backticks (“`
”),
single quotation marks (“'
”),
or double quotation marks
(“"
”).
The user name and host name parts, if quoted, must be quoted
separately. That is, write
'me'@'localhost'
, not
'me@localhost'
; the latter is interpreted
as 'me@localhost'@'%'
.
A reference to the CURRENT_USER
or CURRENT_USER()
function is
equivalent to specifying the current client's user name and
host name literally.
MySQL stores account names in grant tables in the
mysql
database using separate columns for the
user name and host name parts:
The user
table contains one row for each
account. The User
and
Host
columns store the user name and host
name. This table also indicates which global privileges the
account has.
Other grant tables indicate privileges an account has for
databases and objects within databases. These tables have
User
and Host
columns to
store the account name. Each row in these tables associates
with the account in the user
table that has
the same User
and Host
values.
For additional detail about grant table structure, see Section 6.2.2, “Privilege System Grant Tables”.
User names and host names have certain special values or wildcard conventions, as described following.
A user name is either a nonblank value that literally matches the
user name for incoming connection attempts, or a blank value
(empty string) that matches any user name. An account with a blank
user name is an anonymous user. To specify an anonymous user in
SQL statements, use a quoted empty user name part, such as
''@'localhost'
.
The host name part of an account name can take many forms, and wildcards are permitted:
A host value can be a host name or an IP address (IPv4 or
IPv6). The name 'localhost'
indicates the
local host. The IP address '127.0.0.1'
indicates the IPv4 loopback interface. The IP address
'::1'
indicates the IPv6 loopback
interface.
You can use the wildcard characters
“%
” and
“_
” in host name or IP address
values. These have the same meaning as for pattern-matching
operations performed with the
LIKE
operator. For example, a
host value of '%'
matches any host name,
whereas a value of '%.mysql.com'
matches
any host in the mysql.com
domain.
'192.168.1.%'
matches any host in the
192.168.1 class C network.
Because you can use IP wildcard values in host values (for
example, '192.168.1.%'
to match every host
on a subnet), someone could try to exploit this capability by
naming a host 192.168.1.somewhere.com
. To
foil such attempts, MySQL disallows matching on host names
that start with digits and a dot. Thus, if you have a host
named something like 1.2.example.com
, its
name never matches the host part of account names. An IP
wildcard value can match only IP addresses, not host names.
For a host value specified as an IPv4 address, you can specify a netmask indicating how many address bits to use for the network number. Netmask notation cannot be used for IPv6 addresses.
The syntax is
.
For example:
host_ip
/netmask
CREATE USER 'david'@'192.58.197.0/255.255.255.0';
This enables david
to connect from any
client host having an IP address
client_ip
for which the following
condition is true:
client_ip
&netmask
=host_ip
That is, for the CREATE USER
statement just shown:
client_ip
& 255.255.255.0 = 192.58.197.0
IP addresses that satisfy this condition and can connect to
the MySQL server are those in the range from
192.58.197.0
to
192.58.197.255
.
A netmask typically begins with bits set to 1, followed by bits set to 0. Examples:
192.0.0.0/255.0.0.0
: Any host on the
192 class A network
192.168.0.0/255.255.0.0
: Any host on
the 192.168 class B network
192.168.1.0/255.255.255.0
: Any host on
the 192.168.1 class C network
192.168.1.1
: Only the host with this
specific IP address
The following netmask will not work because it masks 28 bits, and 28 is not a multiple of 8:
192.168.0.1/255.255.255.240
The server performs matching of host values in account names against the client host using the value returned by the system DNS resolver for the client host name or IP address. Except in the case that the account host value is specified using netmask notation, this comparison is performed as a string match, even for an account host value given as an IP address. This means that you should specify account host values in the same format used by DNS. Here are examples of problems to watch out for:
Suppose that a host on the local network has a fully qualified
name of host1.example.com
. If DNS returns
name lookups for this host as
host1.example.com
, use that name in account
host values. But if DNS returns just host1
,
use host1
instead.
If DNS returns the IP address for a given host as
192.168.1.2
, that will match an account
host value of 192.168.1.2
but not
192.168.01.2
. Similarly, it will match an
account host pattern like 192.168.1.%
but
not 192.168.01.%
.
To avoid problems like this, it is advisable to check the format in which your DNS returns host names and addresses, and use values in the same format in MySQL account names.
When you attempt to connect to a MySQL server, the server accepts or rejects the connection based on these conditions:
Your identity and whether you can verify your identity by supplying the correct password
Whether your account is locked or unlocked
The server checks credentials first, then account locking state. A failure for either step causes the server to deny access to you completely. Otherwise, the server accepts the connection, and then enters Stage 2 and waits for requests.
Credential checking is performed using the three
user
table scope columns
(Host
, User
, and
Password
). Locking state is recorded in the
user
table account_locked
column. The server accepts the connection only if the
Host
and User
columns in
some user
table row match the client host name
and user name, the client supplies the password specified in that
row, and the account_locked
value is
'N'
. The rules for permissible
Host
and User
values are
given in Section 6.2.3, “Specifying Account Names”. Account locking can be
changed with the ALTER USER
statement.
Your identity is based on two pieces of information:
The client host from which you connect
Your MySQL user name
If the User
column value is nonblank, the user
name in an incoming connection must match exactly. If the
User
value is blank, it matches any user name.
If the user
table row that matches an incoming
connection has a blank user name, the user is considered to be an
anonymous user with no name, not a user with the name that the
client actually specified. This means that a blank user name is
used for all further access checking for the duration of the
connection (that is, during Stage 2).
The Password
column can be blank. This is not a
wildcard and does not mean that any password matches. It means
that the user must connect without specifying a password. If the
server authenticates a client using a plugin, the authentication
method that the plugin implements may or may not use the password
in the Password
column. In this case, it is
possible that an external password is also used to authenticate to
the MySQL server.
Nonblank Password
values in the
user
table represent encrypted passwords. MySQL
does not store passwords in cleartext form for anyone to see.
Rather, the password supplied by a user who is attempting to
connect is encrypted (using the
PASSWORD()
function). The encrypted
password then is used during the connection process when checking
whether the password is correct. This is done without the
encrypted password ever traveling over the connection. See
Section 6.3.1, “User Names and Passwords”.
From MySQL's point of view, the encrypted password is the
real password, so you should never give
anyone access to it. In particular, do not give
nonadministrative users read access to tables in the
mysql
database.
The following table shows how various combinations of
User
and Host
values in the
user
table apply to incoming connections.
User Value | Host Value | Permissible Connections |
---|---|---|
'fred' | 'thomas.loc.gov' | fred , connecting from
thomas.loc.gov |
'' | 'thomas.loc.gov' | Any user, connecting from thomas.loc.gov |
'fred' | '%' | fred , connecting from any host |
'' | '%' | Any user, connecting from any host |
'fred' | '%.loc.gov' | fred , connecting from any host in the
loc.gov domain |
'fred' | 'x.y.%' | fred , connecting from x.y.net ,
x.y.com , x.y.edu ,
and so on; this is probably not useful |
'fred' | '192.168.10.177' | fred , connecting from the host with IP address
192.168.10.177 |
'fred' | '192.168.10.%' | fred , connecting from any host in the
192.168.10 class C subnet |
'fred' | '192.168.10.0/255.255.255.0' | Same as previous example |
It is possible for the client host name and user name of an
incoming connection to match more than one row in the
user
table. The preceding set of examples
demonstrates this: Several of the entries shown match a connection
from thomas.loc.gov
by fred
.
When multiple matches are possible, the server must determine which of them to use. It resolves this issue as follows:
Whenever the server reads the user
table
into memory, it sorts the rows.
When a client attempts to connect, the server looks through the rows in sorted order.
The server uses the first row that matches the client host name and user name.
The server uses sorting rules that order rows with the
most-specific Host
values first. Literal host
names and IP addresses are the most specific. (The specificity of
a literal IP address is not affected by whether it has a netmask,
so 192.168.1.13
and
192.168.1.0/255.255.255.0
are considered
equally specific.) The pattern '%'
means
“any host” and is least specific. The empty string
''
also means “any host” but sorts
after '%'
. Rows with the same
Host
value are ordered with the most-specific
User
values first (a blank
User
value means “any user” and is
least specific). For rows with equally-specific
Host
and User
values, the
order is indeterminate.
To see how this works, suppose that the user
table looks like this:
+-----------+----------+- | Host | User | ... +-----------+----------+- | % | root | ... | % | jeffrey | ... | localhost | root | ... | localhost | | ... +-----------+----------+-
When the server reads the table into memory, it sorts the rows using the rules just described. The result after sorting looks like this:
+-----------+----------+- | Host | User | ... +-----------+----------+- | localhost | root | ... | localhost | | ... | % | jeffrey | ... | % | root | ... +-----------+----------+-
When a client attempts to connect, the server looks through the
sorted rows and uses the first match found. For a connection from
localhost
by jeffrey
, two of
the rows from the table match: the one with
Host
and User
values of
'localhost'
and ''
, and the
one with values of '%'
and
'jeffrey'
. The 'localhost'
row appears first in sorted order, so that is the one the server
uses.
Here is another example. Suppose that the user
table looks like this:
+----------------+----------+- | Host | User | ... +----------------+----------+- | % | jeffrey | ... | thomas.loc.gov | | ... +----------------+----------+-
The sorted table looks like this:
+----------------+----------+- | Host | User | ... +----------------+----------+- | thomas.loc.gov | | ... | % | jeffrey | ... +----------------+----------+-
A connection by jeffrey
from
thomas.loc.gov
is matched by the first row,
whereas a connection by jeffrey
from any host
is matched by the second.
It is a common misconception to think that, for a given user
name, all rows that explicitly name that user are used first
when the server attempts to find a match for the connection.
This is not true. The preceding example illustrates this, where
a connection from thomas.loc.gov
by
jeffrey
is first matched not by the row
containing 'jeffrey'
as the
User
column value, but by the row with no
user name. As a result, jeffrey
is
authenticated as an anonymous user, even though he specified a
user name when connecting.
If you are able to connect to the server, but your privileges are
not what you expect, you probably are being authenticated as some
other account. To find out what account the server used to
authenticate you, use the
CURRENT_USER()
function. (See
Section 12.14, “Information Functions”.) It returns a value in
format that indicates the user_name
@host_name
User
and
Host
values from the matching
user
table row. Suppose that
jeffrey
connects and issues the following
query:
mysql> SELECT CURRENT_USER();
+----------------+
| CURRENT_USER() |
+----------------+
| @localhost |
+----------------+
The result shown here indicates that the matching
user
table row had a blank
User
column value. In other words, the server
is treating jeffrey
as an anonymous user.
Another way to diagnose authentication problems is to print out
the user
table and sort it by hand to see where
the first match is being made.
After you establish a connection, the server enters Stage 2 of
access control. For each request that you issue through that
connection, the server determines what operation you want to
perform, then checks whether you have sufficient privileges to do
so. This is where the privilege columns in the grant tables come
into play. These privileges can come from any of the
user
, db
,
tables_priv
, columns_priv
,
or procs_priv
tables. (You may find it helpful
to refer to Section 6.2.2, “Privilege System Grant Tables”, which lists
the columns present in each of the grant tables.)
The user
table grants privileges that are
assigned to you on a global basis and that apply no matter what
the default database is. For example, if the
user
table grants you the
DELETE
privilege, you can delete
rows from any table in any database on the server host! It is wise
to grant privileges in the user
table only to
people who need them, such as database administrators. For other
users, you should leave all privileges in the
user
table set to 'N'
and
grant privileges at more specific levels only. You can grant
privileges for particular databases, tables, columns, or routines.
The db
table grants database-specific
privileges. Values in the scope columns of this table can take the
following forms:
A blank User
value matches the anonymous
user. A nonblank value matches literally; there are no
wildcards in user names.
The wildcard characters “%
”
and “_
” can be used in the
Host
and Db
columns.
These have the same meaning as for pattern-matching operations
performed with the LIKE
operator.
If you want to use either character literally when granting
privileges, you must escape it with a backslash. For example,
to include the underscore character
(“_
”) as part of a database
name, specify it as “\_
” in
the GRANT
statement.
A '%'
or blank Host
value means “any host.”
A '%'
or blank Db
value
means “any database.”
The server reads the db
table into memory and
sorts it at the same time that it reads the
user
table. The server sorts the
db
table based on the Host
,
Db
, and User
scope columns.
As with the user
table, sorting puts the
most-specific values first and least-specific values last, and
when the server looks for matching rows, it uses the first match
that it finds.
The tables_priv
,
columns_priv
, and procs_priv
tables grant table-specific, column-specific, and routine-specific
privileges. Values in the scope columns of these tables can take
the following forms:
The wildcard characters “%
”
and “_
” can be used in the
Host
column. These have the same meaning as
for pattern-matching operations performed with the
LIKE
operator.
A '%'
or blank Host
value means “any host.”
The Db
, Table_name
,
Column_name
, and
Routine_name
columns cannot contain
wildcards or be blank.
The server sorts the tables_priv
,
columns_priv
, and procs_priv
tables based on the Host
,
Db
, and User
columns. This
is similar to db
table sorting, but simpler
because only the Host
column can contain
wildcards.
The server uses the sorted tables to verify each request that it
receives. For requests that require administrative privileges such
as SHUTDOWN
or
RELOAD
, the server checks only the
user
table row because that is the only table
that specifies administrative privileges. The server grants access
if the row permits the requested operation and denies access
otherwise. For example, if you want to execute mysqladmin
shutdown but your user
table row does
not grant the SHUTDOWN
privilege to
you, the server denies access without even checking the
db
table. (It contains no
Shutdown_priv
column, so there is no need to do
so.)
For database-related requests
(INSERT
,
UPDATE
, and so on), the server
first checks the user's global privileges by looking in the
user
table row. If the row permits the
requested operation, access is granted. If the global privileges
in the user
table are insufficient, the server
determines the user's database-specific privileges by checking the
db
table:
The server looks in the db
table for a match on
the Host
, Db
, and
User
columns. The Host
and
User
columns are matched to the connecting
user's host name and MySQL user name. The Db
column is matched to the database that the user wants to access.
If there is no row for the Host
and
User
, access is denied.
After determining the database-specific privileges granted by the
db
table rows, the server adds them to the
global privileges granted by the user
table. If
the result permits the requested operation, access is granted.
Otherwise, the server successively checks the user's table and
column privileges in the tables_priv
and
columns_priv
tables, adds those to the user's
privileges, and permits or denies access based on the result. For
stored-routine operations, the server uses the
procs_priv
table rather than
tables_priv
and
columns_priv
.
Expressed in boolean terms, the preceding description of how a user's privileges are calculated may be summarized like this:
global privileges OR (database privileges AND host privileges) OR table privileges OR column privileges OR routine privileges
It may not be apparent why, if the global user
row privileges are initially found to be insufficient for the
requested operation, the server adds those privileges to the
database, table, and column privileges later. The reason is that a
request might require more than one type of privilege. For
example, if you execute an
INSERT INTO ...
SELECT
statement, you need both the
INSERT
and the
SELECT
privileges. Your privileges
might be such that the user
table row grants
one privilege and the db
table row grants the
other. In this case, you have the necessary privileges to perform
the request, but the server cannot tell that from either table by
itself; the privileges granted by the rows in both tables must be
combined.
When mysqld starts, it reads all grant table contents into memory. The in-memory tables become effective for access control at that point.
If you modify the grant tables indirectly using account-management
statements such as GRANT
,
REVOKE
, SET
PASSWORD
, or RENAME USER
,
the server notices these changes and loads the grant tables into
memory again immediately.
If you modify the grant tables directly using statements such as
INSERT
,
UPDATE
, or
DELETE
, your changes have no effect
on privilege checking until you either restart the server or tell
it to reload the tables. If you change the grant tables directly
but forget to reload them, your changes have no
effect until you restart the server. This may leave you
wondering why your changes seem to make no difference!
To tell the server to reload the grant tables, perform a
flush-privileges operation. This can be done by issuing a
FLUSH PRIVILEGES
statement or by executing a mysqladmin
flush-privileges or mysqladmin reload
command.
A grant table reload affects privileges for each existing client connection as follows:
Table and column privilege changes take effect with the client's next request.
Database privilege changes take effect the next time the
client executes a USE
statement.
db_name
Client applications may cache the database name; thus, this effect may not be visible to them without actually changing to a different database or flushing the privileges.
Global privileges and passwords are unaffected for a connected client. These changes take effect only for subsequent connections.
If the server is started with the
--skip-grant-tables
option, it does
not read the grant tables or implement any access control. Anyone
can connect and do anything, which is
insecure. To cause a server thus started to read the
tables and enable access checking, flush the privileges.
If you encounter problems when you try to connect to the MySQL server, the following items describe some courses of action you can take to correct the problem.
Make sure that the server is running. If it is not, clients cannot connect to it. For example, if an attempt to connect to the server fails with a message such as one of those following, one cause might be that the server is not running:
shell>mysql
ERROR 2003: Can't connect to MySQL server on 'host_name
' (111) shell>mysql
ERROR 2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (111)
It might be that the server is running, but you are trying to
connect using a TCP/IP port, named pipe, or Unix socket file
different from the one on which the server is listening. To
correct this when you invoke a client program, specify a
--port
option to indicate the
proper port number, or a
--socket
option to indicate
the proper named pipe or Unix socket file. To find out where
the socket file is, you can use this command:
shell> netstat -ln | grep mysql
Make sure that the server has not been configured to ignore
network connections or (if you are attempting to connect
remotely) that it has not been configured to listen only
locally on its network interfaces. If the server was started
with --skip-networking
, it will
not accept TCP/IP connections at all. If the server was
started with
--bind-address=127.0.0.1
, it
will listen for TCP/IP connections only locally on the
loopback interface and will not accept remote connections.
Check to make sure that there is no firewall blocking access to MySQL. Your firewall may be configured on the basis of the application being executed, or the port number used by MySQL for communication (3306 by default). Under Linux or Unix, check your IP tables (or similar) configuration to ensure that the port has not been blocked. Under Windows, applications such as ZoneAlarm or the Windows XP personal firewall may need to be configured not to block the MySQL port.
The grant tables must be properly set up so that the server
can use them for access control. For some distribution types
(such as binary distributions on Windows, or RPM distributions
on Linux), the installation process initializes the MySQL data
directory, including the mysql
database
containing the grant tables. For distributions that do not do
this, you must initialize the data directory manually. For
details, see Section 2.10, “Postinstallation Setup and Testing”.
To determine whether you need to initialize the grant tables,
look for a mysql
directory under the data
directory. (The data directory normally is named
data
or var
and is
located under your MySQL installation directory.) Make sure
that you have a file named user.MYD
in
the mysql
database directory. If not,
initialize the data directory. After doing so and starting the
server, test the initial privileges by executing this command:
shell> mysql -u root
The server should let you connect without error.
After a fresh installation, you should connect to the server and set up your users and their access permissions:
shell> mysql -u root mysql
The server should let you connect because the MySQL
root
user has no password initially. That
is also a security risk, so setting the password for the
root
account is something you should do
while you're setting up your other MySQL accounts. For
instructions on setting the initial password, see
Section 2.10.4, “Securing the Initial MySQL Accounts”.
If you have updated an existing MySQL installation to a newer version, did you run the mysql_upgrade script? If not, do so. The structure of the grant tables changes occasionally when new capabilities are added, so after an upgrade you should always make sure that your tables have the current structure. For instructions, see Section 4.4.7, “mysql_upgrade — Check and Upgrade MySQL Tables”.
If a client program receives the following error message when it tries to connect, it means that the server expects passwords in a newer format than the client is capable of generating:
shell> mysql
Client does not support authentication protocol requested
by server; consider upgrading MySQL client
For information on how to deal with this, see Section 6.1.2.4, “Password Hashing in MySQL”, and Section B.5.2.4, “Client does not support authentication protocol”.
Remember that client programs use connection parameters
specified in option files or environment variables. If a
client program seems to be sending incorrect default
connection parameters when you have not specified them on the
command line, check any applicable option files and your
environment. For example, if you get Access
denied
when you run a client without any options,
make sure that you have not specified an old password in any
of your option files!
You can suppress the use of option files by a client program
by invoking it with the
--no-defaults
option. For
example:
shell> mysqladmin --no-defaults -u root version
The option files that clients use are listed in Section 4.2.6, “Using Option Files”. Environment variables are listed in Section 2.12, “Environment Variables”.
If you get the following error, it means that you are using an
incorrect root
password:
shell> mysqladmin -u root -pxxxx
ver
Access denied for user 'root'@'localhost' (using password: YES)
If the preceding error occurs even when you have not specified
a password, it means that you have an incorrect password
listed in some option file. Try the
--no-defaults
option as
described in the previous item.
For information on changing passwords, see Section 6.3.5, “Assigning Account Passwords”.
If you have lost or forgotten the root
password, see Section B.5.3.2, “How to Reset the Root Password”.
If you change a password by using SET
PASSWORD
, INSERT
, or
UPDATE
, you must encrypt the
password using the PASSWORD()
function. If you do not use
PASSWORD()
for these
statements, the password will not work. For example, the
following statement assigns a password, but fails to encrypt
it, so the user is not able to connect afterward:
SET PASSWORD FOR 'abe'@'host_name
' = 'eagle';
Instead, set the password like this:
SET PASSWORD FOR 'abe'@'host_name
' = PASSWORD('eagle');
The PASSWORD()
function is
unnecessary when you specify a password using the
CREATE USER
or
GRANT
statements or the
mysqladmin password command. Each of those
automatically uses PASSWORD()
to encrypt the password. See
Section 6.3.5, “Assigning Account Passwords”, and
Section 13.7.1.2, “CREATE USER Syntax”.
localhost
is a synonym for your local host
name, and is also the default host to which clients try to
connect if you specify no host explicitly.
You can use a --host=127.0.0.1
option to name the server host explicitly. This will make a
TCP/IP connection to the local mysqld
server. You can also use TCP/IP by specifying a
--host
option that uses the
actual host name of the local host. In this case, the host
name must be specified in a user
table row
on the server host, even though you are running the client
program on the same host as the server.
The Access denied
error message tells you
who you are trying to log in as, the client host from which
you are trying to connect, and whether you were using a
password. Normally, you should have one row in the
user
table that exactly matches the host
name and user name that were given in the error message. For
example, if you get an error message that contains
using password: NO
, it means that you tried
to log in without a password.
If you get an Access denied
error when
trying to connect to the database with mysql -u
, you may have a
problem with the user_name
user
table. Check this by
executing mysql -u root mysql
and issuing
this SQL statement:
SELECT * FROM user;
The result should include a row with the
Host
and User
columns
matching your client's host name and your MySQL user name.
If the following error occurs when you try to connect from a
host other than the one on which the MySQL server is running,
it means that there is no row in the user
table with a Host
value that matches the
client host:
Host ... is not allowed to connect to this MySQL server
You can fix this by setting up an account for the combination of client host name and user name that you are using when trying to connect.
If you do not know the IP address or host name of the machine
from which you are connecting, you should put a row with
'%'
as the Host
column
value in the user
table. After trying to
connect from the client machine, use a SELECT
USER()
query to see how you really did connect. Then
change the '%'
in the
user
table row to the actual host name that
shows up in the log. Otherwise, your system is left insecure
because it permits connections from any host for the given
user name.
On Linux, another reason that this error might occur is that
you are using a binary MySQL version that is compiled with a
different version of the glibc
library than
the one you are using. In this case, you should either upgrade
your operating system or glibc
, or download
a source distribution of MySQL version and compile it
yourself. A source RPM is normally trivial to compile and
install, so this is not a big problem.
If you specify a host name when trying to connect, but get an error message where the host name is not shown or is an IP address, it means that the MySQL server got an error when trying to resolve the IP address of the client host to a name:
shell> mysqladmin -u root -pxxxx
-h some_hostname
ver
Access denied for user 'root'@'' (using password: YES)
If you try to connect as root
and get the
following error, it means that you do not have a row in the
user
table with a User
column value of 'root'
and that
mysqld cannot resolve the host name for
your client:
Access denied for user ''@'unknown'
These errors indicate a DNS problem. To fix it, execute mysqladmin flush-hosts to reset the internal DNS host cache. See Section 8.12.6.2, “DNS Lookup Optimization and the Host Cache”.
Some permanent solutions are:
Determine what is wrong with your DNS server and fix it.
Specify IP addresses rather than host names in the MySQL grant tables.
Put an entry for the client machine name in
/etc/hosts
on Unix or
\windows\hosts
on Windows.
Start mysqld with the
--skip-name-resolve
option.
Start mysqld with the
--skip-host-cache
option.
On Unix, if you are running the server and the client on
the same machine, connect to localhost
.
For connections to localhost
, MySQL
programs attempt to connect to the local server by using a
Unix socket file, unless there are connection parameters
specified to ensure that the client makes a TCP/IP
connection. For more information, see
Section 4.2.2, “Connecting to the MySQL Server”.
On Windows, if you are running the server and the client
on the same machine and the server supports named pipe
connections, connect to the host name .
(period). Connections to .
use a named
pipe rather than TCP/IP.
If mysql -u root
works but mysql
-h
results in your_hostname
-u rootAccess denied
(where
your_hostname
is the actual host
name of the local host), you may not have the correct name for
your host in the user
table. A common
problem here is that the Host
value in the
user
table row specifies an unqualified
host name, but your system's name resolution routines return a
fully qualified domain name (or vice versa). For example, if
you have a row with host 'pluto'
in the
user
table, but your DNS tells MySQL that
your host name is 'pluto.example.com'
, the
row does not work. Try adding a row to the
user
table that contains the IP address of
your host as the Host
column value.
(Alternatively, you could add a row to the
user
table with a Host
value that contains a wildcard; for example,
'pluto.%'
. However, use of
Host
values ending with
“%
” is
insecure and is not
recommended!)
If mysql -u
works but
user_name
mysql -u
does not, you
have not granted access to the given user for the database
named user_name
some_db
some_db
.
If mysql -u
works when
executed on the server host, but user_name
mysql -h
does not work
when executed on a remote client host, you have not enabled
access to the server for the given user name from the remote
host.
host_name
-u
user_name
If you cannot figure out why you get Access
denied
, remove from the user
table all rows that have Host
values
containing wildcards (rows that contain '%'
or '_'
characters). A very common error is
to insert a new row with
Host
='%'
and
User
='
,
thinking that this enables you to specify
some_user
'localhost
to connect from the same machine.
The reason that this does not work is that the default
privileges include a row with
Host
='localhost'
and
User
=''
. Because that
row has a Host
value
'localhost'
that is more specific than
'%'
, it is used in preference to the new
row when connecting from localhost
! The
correct procedure is to insert a second row with
Host
='localhost'
and
User
='
,
or to delete the row with
some_user
'Host
='localhost'
and
User
=''
. After deleting
the row, remember to issue a
FLUSH
PRIVILEGES
statement to reload the grant tables. See
also Section 6.2.4, “Access Control, Stage 1: Connection Verification”.
If you are able to connect to the MySQL server, but get an
Access denied
message whenever you issue a
SELECT ... INTO
OUTFILE
or
LOAD DATA
INFILE
statement, your row in the
user
table does not have the
FILE
privilege enabled.
If you change the grant tables directly (for example, by using
INSERT
,
UPDATE
, or
DELETE
statements) and your
changes seem to be ignored, remember that you must execute a
FLUSH
PRIVILEGES
statement or a mysqladmin
flush-privileges command to cause the server to
reload the privilege tables. Otherwise, your changes have no
effect until the next time the server is restarted. Remember
that after you change the root
password
with an UPDATE
statement, you
will not need to specify the new password until after you
flush the privileges, because the server will not know you've
changed the password yet!
If your privileges seem to have changed in the middle of a session, it may be that a MySQL administrator has changed them. Reloading the grant tables affects new client connections, but it also affects existing connections as indicated in Section 6.2.6, “When Privilege Changes Take Effect”.
If you have access problems with a Perl, PHP, Python, or ODBC
program, try to connect to the server with mysql -u
or user_name
db_name
mysql
-u
. If you are able
to connect using the mysql client, the
problem lies with your program, not with the access
privileges. (There is no space between user_name
-pyour_pass
db_name
-p
and
the password; you can also use the
--password=
syntax to specify the password. If you use the
your_pass
-p
or
--password
option with no
password value, MySQL prompts you for the password.)
For testing purposes, start the mysqld
server with the
--skip-grant-tables
option.
Then you can change the MySQL grant tables and use the
SHOW GRANTS
statement to check
whether your modifications have the desired effect. When you
are satisfied with your changes, execute mysqladmin
flush-privileges to tell the
mysqld server to reload the privileges.
This enables you to begin using the new grant table contents
without stopping and restarting the server.
If everything else fails, start the mysqld
server with a debugging option (for example,
--debug=d,general,query
). This
prints host and user information about attempted connections,
as well as information about each command issued. See
Section 25.5.3, “The DBUG Package”.
If you have any other problems with the MySQL grant tables and
feel you must post the problem to the mailing list, always
provide a dump of the MySQL grant tables. You can dump the
tables with the mysqldump mysql command. To
file a bug report, see the instructions at
Section 1.7, “How to Report Bugs or Problems”. In some cases, you may need to
restart mysqld with
--skip-grant-tables
to run
mysqldump.
This section describes how to set up accounts for clients of your MySQL server. It discusses the following topics:
The meaning of account names and passwords as used in MySQL and how that compares to names and passwords used by your operating system
How to set up new accounts and remove existing accounts
How to change passwords
Guidelines for using passwords securely
How to use secure connections
See also Section 13.7.1, “Account Management Statements”, which describes the syntax and use for all user-management SQL statements.
MySQL stores accounts in the user
table of the
mysql
system database. An account is defined in
terms of a user name and the client host or hosts from which the
user can connect to the server. For information about account
representation in the user
table, see
Section 6.2.2, “Privilege System Grant Tables”.
The account may also have a password. MySQL supports authentication plugins, so it is possible that an account authenticates using some external authentication method. See Section 6.3.8, “Pluggable Authentication”.
There are several distinctions between the way user names and passwords are used by MySQL and your operating system:
User names, as used by MySQL for authentication purposes, have
nothing to do with user names (login names) as used by Windows
or Unix. On Unix, most MySQL clients by default try to log in
using the current Unix user name as the MySQL user name, but
that is for convenience only. The default can be overridden
easily, because client programs permit any user name to be
specified with a -u
or
--user
option. This means that anyone can
attempt to connect to the server using any user name, so you
cannot make a database secure in any way unless all MySQL
accounts have passwords. Anyone who specifies a user name for
an account that has no password is able to connect
successfully to the server.
MySQL user names can be up to 32 characters long (16 characters before MySQL 5.7.8). Operating system user names may be of a different maximum length. For example, Unix user names typically are limited to eight characters.
The limit on MySQL user name length is hardcoded in MySQL
servers and clients, and trying to circumvent it by
modifying the definitions of the tables in the
mysql
database does not
work.
You should never alter the structure of tables in the
mysql
database in any manner whatsoever
except by means of the procedure that is described in
Section 4.4.7, “mysql_upgrade — Check and Upgrade MySQL Tables”. Attempting to redefine
MySQL's system tables in any other fashion results in
undefined (and unsupported!) behavior. The server is free to
ignore rows that become malformed as a result of such
modifications.
To authenticate client connections for accounts that use MySQL
native authentication (implemented by the
mysql_native_password
authentication
plugin), the server uses passwords stored in the
user
table. These passwords are distinct
from passwords for logging in to your operating system. There
is no necessary connection between the “external”
password you use to log in to a Windows or Unix machine and
the password you use to access the MySQL server on that
machine.
If the server authenticates a client using some other plugin,
the authentication method that the plugin implements may or
may not use a password stored in the user
table. In this case, it is possible that an external password
is also used to authenticate to the MySQL server.
Passwords stored in the user
table are
encrypted using plugin-specific algorithms. For information
about MySQL native password hashing, see
Section 6.1.2.4, “Password Hashing in MySQL”.
If the user name and password contain only ASCII characters,
it is possible to connect to the server regardless of
character set settings. To connect when the user name or
password contain non-ASCII characters, the client should call
the mysql_options()
C API
function with the MYSQL_SET_CHARSET_NAME
option and appropriate character set name as arguments. This
causes authentication to take place using the specified
character set. Otherwise, authentication will fail unless the
server default character set is the same as the encoding in
the authentication defaults.
Standard MySQL client programs support a
--default-character-set
option that causes
mysql_options()
to be called
as just described. In addition, character set autodetection is
supported as described in
Section 10.1.4, “Connection Character Sets and Collations”. For programs that use a
connector that is not based on the C API, the connector may
provide an equivalent to
mysql_options()
that can be
used instead. Check the connector documentation.
The preceding notes do not apply for ucs2
,
utf16
, and utf32
, which
are not permitted as client character sets.
The MySQL installation process populates the grant tables with an
initial root
account, as described in
Section 2.10.4, “Securing the Initial MySQL Accounts”, which also discusses how to
assign passwords to it. Thereafter, you normally set up, modify,
and remove MySQL accounts using statements such as
CREATE USER
,
DROP USER
,
GRANT
, and
REVOKE
. See
Section 13.7.1, “Account Management Statements”.
To connect to a MySQL server with a command-line client, specify user name and password options as necessary for the account that you want to use:
shell> mysql --user=monty --password db_name
If you prefer short options, the command looks like this:
shell> mysql -u monty -p db_name
If you omit the password value following the
--password
or -p
option on the command line (as just shown), the client prompts for
one. Alternatively, the password can be specified on the command
line:
shell>mysql --user=monty --password=
shell>password
db_name
mysql -u monty -p
password
db_name
If you use the -p
option, there must be
no space between -p
and the
following password value.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1, “End-User Guidelines for Password Security”. You can use an option file or a login path file to avoid giving the password on the command line. See Section 4.2.6, “Using Option Files”, and Section 4.6.6, “mysql_config_editor — MySQL Configuration Utility”.
For additional information about specifying user names, passwords, and other connection parameters, see Section 4.2.2, “Connecting to the MySQL Server”.
You can create MySQL accounts two ways:
By using account-management statements intended for creating
accounts and establishing their privileges, such as
CREATE USER
and
GRANT
. These statements cause
the server to make appropriate modifications to the underlying
grant tables.
By manipulating the MySQL grant tables directly with
statements such as INSERT
,
UPDATE
, or
DELETE
.
The preferred method is to use account-management statements because they are more concise and less error-prone than manipulating the grant tables directly. All such statements are described in Section 13.7.1, “Account Management Statements”. Direct grant table manipulation is discouraged, and is not described here. The server is free to ignore rows that become malformed as a result of such modifications.
Another option for creating accounts is to use the GUI tool
MySQL Workbench. Also, several third-party programs offer capabilities
for MySQL account administration. phpMyAdmin
is
one such program.
The following examples show how to use the
mysql client program to set up new accounts.
These examples assume that privileges have been set up according
to the defaults described in Section 2.10.4, “Securing the Initial MySQL Accounts”.
This means that to make changes, you must connect to the MySQL
server as the MySQL root
user, which has the
CREATE USER
privilege.
First, use the mysql program to connect to the
server as the MySQL root
user:
shell> mysql --user=root mysql
If you have assigned a password to the root
account, you must also supply a --password
or
-p
option.
After connecting to the server as root
, you can
add new accounts. The following example uses
CREATE USER
and
GRANT
statements to set up four
accounts:
mysql>CREATE USER 'monty'@'localhost' IDENTIFIED BY 'some_pass';
mysql>GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost'
->WITH GRANT OPTION;
mysql>CREATE USER 'monty'@'%' IDENTIFIED BY 'some_pass';
mysql>GRANT ALL PRIVILEGES ON *.* TO 'monty'@'%'
->WITH GRANT OPTION;
mysql>CREATE USER 'admin'@'localhost' IDENTIFIED BY 'admin_pass';
mysql>GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost';
mysql>CREATE USER 'dummy'@'localhost';
The accounts created by those statements have the following properties:
Two accounts have a user name of monty
and
a password of some_pass
. Both are superuser
accounts with full privileges to do anything. The
'monty'@'localhost'
account can be used
only when connecting from the local host. The
'monty'@'%'
account uses the
'%'
wildcard for the host part, so it can
be used to connect from any host.
The 'monty'@'localhost'
account is
necessary if there is an anonymous-user account for
localhost
. Without the
'monty'@'localhost'
account, that
anonymous-user account takes precedence when
monty
connects from the local host and
monty
is treated as an anonymous user. The
reason for this is that the anonymous-user account has a more
specific Host
column value than the
'monty'@'%'
account and thus comes earlier
in the user
table sort order.
(user
table sorting is discussed in
Section 6.2.4, “Access Control, Stage 1: Connection Verification”.)
The 'admin'@'localhost'
account has a
password of admin_pass
. This account can be
used only by admin
to connect from the
local host. It is granted the
RELOAD
and
PROCESS
administrative
privileges. These privileges enable the
admin
user to execute the
mysqladmin reload, mysqladmin
refresh, and mysqladmin
flush-xxx
commands, as
well as mysqladmin processlist . No
privileges are granted for accessing any databases. You could
add such privileges using GRANT
statements.
The 'dummy'@'localhost'
account has no
password (which is insecure and not recommended). This account
can be used only to connect from the local host. No privileges
are granted. It is assumed that you will grant specific
privileges to the account using
GRANT
statements.
To see the privileges for an account, use
SHOW GRANTS
:
mysql> SHOW GRANTS FOR 'admin'@'localhost';
+-----------------------------------------------------+
| Grants for admin@localhost |
+-----------------------------------------------------+
| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' |
+-----------------------------------------------------+
To see nonprivilege properties for an account, use
SHOW CREATE USER
:
mysql> SHOW CREATE USER 'admin'@'localhost'\G
*************************** 1. row ***************************
CREATE USER for admin@localhost: CREATE USER 'admin'@'localhost'
IDENTIFIED WITH 'mysql_native_password'
AS '*67ACDEBDAB923990001F0FFB017EB8ED41861105'
REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK
The next examples create three accounts and grant them access to
specific databases. Each of them has a user name of
custom
and password of
obscure
:
mysql>CREATE USER 'custom'@'localhost' IDENTIFIED BY 'obscure';
mysql>GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
->ON bankaccount.*
->TO 'custom'@'localhost';
mysql>CREATE USER 'custom'@'host47.example.com' IDENTIFIED BY 'obscure';
mysql>GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
->ON expenses.*
->TO 'custom'@'host47.example.com';
mysql>CREATE USER 'custom'@'%.example.com' IDENTIFIED BY 'obscure';
mysql>GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
->ON customer.*
->TO 'custom'@'%.example.com';
The three accounts can be used as follows:
The first account can access the
bankaccount
database, but only from the
local host.
The second account can access the expenses
database, but only from the host
host47.example.com
.
The third account can access the customer
database, from any host in the example.com
domain. This account has access from all machines in the
domain due to use of the “%
”
wildcard character in the host part of the account name.
To remove an account, use the DROP
USER
statement, which is described in
Section 13.7.1.3, “DROP USER Syntax”. For example:
mysql> DROP USER 'jeffrey'@'localhost';
One means of restricting client use of MySQL server resources is
to set the global
max_user_connections
system
variable to a nonzero value. This limits the number of
simultaneous connections that can be made by any given account,
but places no limits on what a client can do once connected. In
addition, setting
max_user_connections
does not
enable management of individual accounts. Both types of control
are of interest to MySQL administrators.
To address such concerns, MySQL permits limits for individual accounts on use of these server resources:
The number of queries an account can issue per hour
The number of updates an account can issue per hour
The number of times an account can connect to the server per hour
The number of simultaneous connections to the server by an account
Any statement that a client can issue counts against the query limit, unless its results are served from the query cache. Only statements that modify databases or tables count against the update limit.
An “account” in this context corresponds to a row in
the mysql.user
table. That is, a connection is
assessed against the User
and
Host
values in the user
table row that applies to the connection. For example, an account
'usera'@'%.example.com'
corresponds to a row in
the user
table that has User
and Host
values of usera
and
%.example.com
, to permit
usera
to connect from any host in the
example.com
domain. In this case, the server
applies resource limits in this row collectively to all
connections by usera
from any host in the
example.com
domain because all such connections
use the same account.
Before MySQL 5.0.3, an “account” was assessed against
the actual host from which a user connects. This older method of
accounting may be selected by starting the server with the
--old-style-user-limits
option. In
this case, if usera
connects simultaneously
from host1.example.com
and
host2.example.com
, the server applies the
account resource limits separately to each connection. If
usera
connects again from
host1.example.com
, the server applies the
limits for that connection together with the existing connection
from that host.
To establish resource limits for an account at account-creation
time, use the CREATE USER
statement. To modify the limits for an existing account, use
ALTER USER
. (Before MySQL 5.7.6,
use GRANT
, for new or existing
accounts.) Provide a WITH
clause that names
each resource to be limited. The default value for each limit is
zero (no limit). For example, to create a new account that can
access the customer
database, but only in a
limited fashion, issue these statements:
mysql>CREATE USER 'francis'@'localhost' IDENTIFIED BY 'frank'
->WITH MAX_QUERIES_PER_HOUR 20
->MAX_UPDATES_PER_HOUR 10
->MAX_CONNECTIONS_PER_HOUR 5
->MAX_USER_CONNECTIONS 2;
The limit types need not all be named in the
WITH
clause, but those named can be present in
any order. The value for each per-hour limit should be an integer
representing a count per hour. For
MAX_USER_CONNECTIONS
, the limit is an integer
representing the maximum number of simultaneous connections by the
account. If this limit is set to zero, the global
max_user_connections
system
variable value determines the number of simultaneous connections.
If max_user_connections
is also
zero, there is no limit for the account.
To modify limits for an existing account, use an
ALTER USER
statement. The following
statement changes the query limit for francis
to 100:
mysql> ALTER USER 'francis'@'localhost' WITH MAX_QUERIES_PER_HOUR 100;
The statement modifies only the limit value specified and leaves the account otherwise unchanged.
To remove a limit, set its value to zero. For example, to remove
the limit on how many times per hour francis
can connect, use this statement:
mysql> ALTER USER 'francis'@'localhost' WITH MAX_CONNECTIONS_PER_HOUR 0;
As mentioned previously, the simultaneous-connection limit for an
account is determined from the
MAX_USER_CONNECTIONS
limit and the
max_user_connections
system
variable. Suppose that the global
max_user_connections
value is 10
and three accounts have individual resource limits specified as
follows:
ALTER USER 'user1'@'localhost' WITH MAX_USER_CONNECTIONS 0; ALTER USER 'user2'@'localhost' WITH MAX_USER_CONNECTIONS 5; ALTER USER 'user3'@'localhost' WITH MAX_USER_CONNECTIONS 20;
user1
has a connection limit of 10 (the global
max_user_connections
value)
because it has a MAX_USER_CONNECTIONS
limit of
zero. user2
and user3
have
connection limits of 5 and 20, respectively, because they have
nonzero MAX_USER_CONNECTIONS
limits.
The server stores resource limits for an account in the
user
table row corresponding to the account.
The max_questions
,
max_updates
, and
max_connections
columns store the per-hour
limits, and the max_user_connections
column
stores the MAX_USER_CONNECTIONS
limit. (See
Section 6.2.2, “Privilege System Grant Tables”.)
Resource-use counting takes place when any account has a nonzero limit placed on its use of any of the resources.
As the server runs, it counts the number of times each account uses resources. If an account reaches its limit on number of connections within the last hour, the server rejects further connections for the account until that hour is up. Similarly, if the account reaches its limit on the number of queries or updates, the server rejects further queries or updates until the hour is up. In all such cases, the server issues appropriate error messages.
Resource counting occurs per account, not per client. For example, if your account has a query limit of 50, you cannot increase your limit to 100 by making two simultaneous client connections to the server. Queries issued on both connections are counted together.
The current per-hour resource-use counts can be reset globally for all accounts, or individually for a given account:
To reset the current counts to zero for all accounts, issue a
FLUSH
USER_RESOURCES
statement. The counts also can be
reset by reloading the grant tables (for example, with a
FLUSH
PRIVILEGES
statement or a mysqladmin
reload command).
The counts for an individual account can be reset to zero by setting any of its limits again. Specify a limit value equal to the value currently assigned to the account.
Per-hour counter resets do not affect the
MAX_USER_CONNECTIONS
limit.
All counts begin at zero when the server starts. Counts do not carry over through server restarts.
For the MAX_USER_CONNECTIONS
limit, an edge
case can occur if the account currently has open the maximum
number of connections permitted to it: A disconnect followed
quickly by a connect can result in an error
(ER_TOO_MANY_USER_CONNECTIONS
or
ER_USER_LIMIT_REACHED
) if the
server has not fully processed the disconnect by the time the
connect occurs. When the server finishes disconnect processing,
another connection will once more be permitted.
Required credentials for clients that connect to the MySQL server can include a password. This section describes how to assign passwords for MySQL accounts.
MySQL stores passwords in the user
table in the
mysql
system database. Operations that assign
or modify passwords are permitted only to users with the
CREATE USER
privilege, or,
alternatively, privileges for the mysql
database (INSERT
privilege to
create new accounts, UPDATE
privilege to modify existing accounts). If the
read_only
system variable is
enabled, use of account-modification statements such as
CREATE USER
or
SET PASSWORD
additionally requires
the SUPER
privilege.
The discussion here summarizes syntax only for the most common password-assignment statements. For complete details on other possibilities, see Section 13.7.1.2, “CREATE USER Syntax”, Section 13.7.1.1, “ALTER USER Syntax”, Section 13.7.1.4, “GRANT Syntax”, and Section 13.7.1.7, “SET PASSWORD Syntax”.
MySQL hashes passwords stored in the mysql.user
table to obfuscate them. For most statements described here, MySQL
automatically hashes the password specified. An exception is
SET PASSWORD ... =
PASSWORD('
, for
which you use the auth_string
')PASSWORD()
function explicitly to hash the password. There are also syntaxes
for CREATE USER
,
ALTER USER
,
GRANT
, and SET
PASSWORD
that permit hashed values to be specified
literally; for details, see the descriptions of those statements.
MySQL uses plugins to perform client authentication; see Section 6.3.8, “Pluggable Authentication”. The authentication plugin associated with an account determines the algorithm used to hash passwords for that account.
To assign a password when you create a new account, use
CREATE USER
and include an
IDENTIFIED BY
clause:
mysql>CREATE USER 'jeffrey'@'localhost'
->IDENTIFIED BY 'mypass';
For this CREATE USER
syntax, MySQL
automatically hashes the password before storing it in the
mysql.user
table.
CREATE USER
also supports syntax
for specifying the account authentication plugin. See
Section 13.7.1.2, “CREATE USER Syntax”.
To assign or change a password for an existing account, use one of the following methods:
Use the ALTER USER
statement
with an IDENTIFIED BY
clause:
mysql>ALTER USER 'jeffrey'@'localhost'
->IDENTIFIED BY 'mypass';
If you are not connected as an anonymous user, you can change your own password without naming your own account literally:
mysql>ALTER USER USER()
->IDENTIFIED BY 'mypass';
For these ALTER USER
syntaxes,
MySQL automatically hashes the password before storing it in
the mysql.user
table.
ALTER USER
syntax for changing
passwords is available as of MySQL 5.7.6.
Use SET PASSWORD
with the
PASSWORD()
function:
mysql>SET PASSWORD FOR
->'jeffrey'@'localhost' = PASSWORD('mypass');
If you are not connected as an anonymous user, you can change
your own password by omitting the FOR
clause:
mysql> SET PASSWORD = PASSWORD('mypass');
The PASSWORD()
function hashes
the password using the hashing method determined by the value
of the old_passwords
system
variable value. If SET PASSWORD
rejects the hashed password value returned by
PASSWORD()
as not being in the
correct format, it may be necessary to change
old_passwords
to change the
hashing method. See Section 13.7.1.7, “SET PASSWORD Syntax”.
Use of SET
PASSWORD ... =
PASSWORD('
for password modification is deprecated as of MySQL 5.7.6.
Use auth_string
')ALTER USER
instead.
Use SET PASSWORD
without the
PASSWORD()
function:
For this syntax, the meaning differs in MySQL 5.7.6 and higher from earlier versions:
As of MySQL 5.7.6, SET
PASSWORD
interprets the string as a cleartext
string and hashes it appropriately for the account
authentication plugin before storing it in the
mysql.user
account row.
mysql>SET PASSWORD FOR
->'jeffrey'@'localhost' = 'mypass';
Before MySQL 5.7.6, SET
PASSWORD
interprets the string as a hashed
password value to be stored directly.
mysql>SET PASSWORD FOR
->'jeffrey'@'localhost' = '*6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4';
The string must be hashed in the format required by the
account authentication plugin. A string not hashed
appropriately causes client connections for the account to
fail with an Access denied
error.
Use a GRANT
USAGE
statement at the global level (ON
*.*
) to change an account password without affecting
the account's current privileges:
mysql>GRANT USAGE ON *.* TO 'jeffrey'@'localhost'
->IDENTIFIED BY 'mypass';
For this GRANT
syntax, MySQL
automatically hashes the password before storing it in the
mysql.user
table.
Use of GRANT
for password
modification is deprecated as of MySQL 5.7.6. Use
ALTER USER
instead.
To change an account password from the command line, use the mysqladmin command:
shell> mysqladmin -u user_name
-h host_name
password "new_password
"
The account for which this command sets the password is the
one with a mysql.user
table row that
matches user_name
in the
User
column and the client host
from which you connect in the
Host
column.
For password changes made using mysqladmin,
MySQL automatically hashes the password before storing it in
the mysql.user
table.
MySQL enables database administrators to expire account passwords manually, and to establish a policy for automatic password expiration.
To expire a password manually, the database administrator uses the
ALTER USER
statement:
ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE;
This operation marks the password expired in the corresponding
mysql.user
table row.
Automatic password expiration is available in MySQL 5.7.4 and
later. The mysql.user
table indicates for each
account when its password was last changed, and the server
automatically treats the password as expired at client connection
time if it is past its permitted lifetime. This works with no
explicit manual password expiration.
The default_password_lifetime
system variable defines the global automatic password expiration
policy. It applies to accounts that use MySQL built-in
authentication methods (accounts that use an authentication plugin
of mysql_native_password
,
mysql_old_password
, or
sha256_password
).
The default
default_password_lifetime
value
is 0, which disables automatic password expiration. If the value
of default_password_lifetime
is a
positive integer N
, it indicates the
permitted password lifetime; passwords must be changed every
N
days.
From MySQL 5.7.4 to 5.7.10, the default
default_password_lifetime
value
is 360 (passwords must be changed approximately once per year).
For those versions, be aware that, if you make no changes to the
default_password_lifetime
variable or to individual user accounts, all user passwords will
expire after 360 days, and all user accounts will start running
in restricted mode when this happens. Clients (which are
effectively users) connecting to the server will then get an
error indicating that the password must be changed:
ERROR 1820 (HY000): You must reset your password using
ALTER USER statement before executing this statement.
However, this is easy to miss for clients that automatically connect to the server, such as connections made from scripts. To avoid having such clients suddenly stop working due to a password expiring, make sure to change the password expiration settings for those clients, like this:
ALTER USER 'script'@'localhost' PASSWORD EXPIRE NEVER
Alternatively, set the
default_password_lifetime
variable to 0
, thus disabling automatic
password expiration for all users.
Examples:
To establish a global policy that passwords have a lifetime of approximately six months, start the server with these lines in an option file:
[mysqld] default_password_lifetime=180
To establish a global policy such that passwords never expire,
set default_password_lifetime
to 0:
[mysqld] default_password_lifetime=0
default_password_lifetime
can
also be changed at runtime (this requires the
SUPER
privilege):
SET GLOBAL default_password_lifetime = 180; SET GLOBAL default_password_lifetime = 0;
No matter the global policy, it can be overridden for individual
accounts with ALTER USER
:
Require the password to be changed every 90 days:
ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE INTERVAL 90 DAY;
Disable password expiration:
ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE NEVER;
Defer to the global expiration policy:
ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE DEFAULT;
These ALTER USER
statements update
the corresponding mysql.user
table row.
When a client successfully connects, the server determines whether the account password is expired:
The server checks whether the password has been manually expired and, if so, restricts the session.
Otherwise, the server checks whether the password is past its lifetime according to the automatic password expiration policy. If so, the server considers the password expired and restricts the session.
A restricted client operates in “sandbox mode,”, which limits the operations permitted to the client (see Section 6.3.7, “Password Expiration and Sandbox Mode”). Operations performed by a restricted client result in an error until the user establishes a new account password:
mysql>SELECT 1;
ERROR 1820 (HY000): You must SET PASSWORD before executing this statement mysql>ALTER USER USER() IDENTIFIED BY '
Query OK, 0 rows affected (0.01 sec) mysql>new_password
';SELECT 1;
+---+ | 1 | +---+ | 1 | +---+ 1 row in set (0.00 sec)
This restricted mode of operation permits
SET
statements, which is useful before MySQL 5.7.6 if
SET PASSWORD
must be used instead
of ALTER USER
and the account
password has a hashing format that requires
old_passwords
to be set to a
value different from its default.
It is possible for an administrative user to reset the account password, but any existing sessions for that account remain restricted. A client using the account must disconnect and reconnect before statements can be executed successfully.
It is possible to “reset” a password by setting it to its current value. As a matter of good policy, it is preferable to choose a different password.
MySQL provides password-expiration capability to enable database administrators to expire account passwords and require users to reset their password. This section describes how password expiration works.
To expire an account password, use the ALTER
USER
statement. For example:
ALTER USER 'myuser'@'localhost' PASSWORD EXPIRE;
This statement modifies the row of the
mysql.user
table associated with the named
account, setting the password_expired
column to
'Y'
. This does not affect any current
connections the account has open. For each subsequent connection
that uses the account, the server either disconnects the client or
handles the client in “sandbox mode,” in which the
server permits to the client only those operations necessary to
reset the expired password. The action taken by the server depends
on both client and server settings.
If the server disconnects the client, it returns an
ER_MUST_CHANGE_PASSWORD_LOGIN
error:
shell>mysql -u myuser -p
Password:******
ERROR 1862 (HY000): Your password has expired. To log in you must change it using a client that supports expired passwords.
If the server puts the client in sandbox mode, these operations are permitted within the client session:
The client can reset the account password with
ALTER USER
or
SET PASSWORD
. This modifies the
row of the mysql.user
table associated with
the current account, setting the
password_expired
column to
'N'
. After the password has been reset, the
server restores normal access for the session, as well as for
subsequent connections that use the account.
It is possible to “reset” a password by setting it to its current value. As a matter of good policy, it is preferable to choose a different password.
The client can use
SET
statements, which is useful before MySQL 5.7.6 if
SET PASSWORD
must be used
instead of ALTER USER
and the
account password has a hashing format that requires
old_passwords
to be set to a
value different from its default.
For any operation not permitted within the session, the server
returns an ER_MUST_CHANGE_PASSWORD
error:
mysql>USE performance_schema;
ERROR 1820 (HY000): You must SET PASSWORD before executing this statement mysql>SELECT 1;
ERROR 1820 (HY000): You must SET PASSWORD before executing this statement
For noninteractive invocations of the mysql
client (for example, in batch mode), the server normally
disconnects the client if the password is expired. To permit
mysql to stay connected so that the password
can be changed (using the statements just described), add the
--connect-expired-password
option to
the mysql command.
As mentioned previously, whether the server disconnects an expired-password client or puts it in sandbox mode depends on a combination of client and server settings. The following discussion describes the relevant settings and how they interact.
On the client side, a given client indicates whether it can handle sandbox mode for expired passwords. For clients that use the C client library, there are two ways to do this:
Pass the
MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS
flag
to mysql_options()
prior to
connecting:
arg = 1; result = mysql_options(mysql, MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS, &arg);
The mysql client enables
MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS
if
invoked interactively or the
--connect-expired-password
option is given.
Pass the
CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS
flag to
mysql_real_connect()
at
connection time:
mysql = mysql_real_connect(mysql, host, user, password, "test", port, unix_socket, CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS);
Other MySQL Connectors have their own conventions for indicating readiness to handle sandbox mode. See the relevant Connector documentation.
On the server side, if a client indicates that it can handle expired passwords, the server puts it in sandbox mode.
If a client does not indicate that it can handle expired passwords
(or uses an older version of the client library that cannot so
indicate), the server action depends on the value of the
disconnect_on_expired_password
system variable:
If
disconnect_on_expired_password
is enabled (the default), the server disconnects the client
with an
ER_MUST_CHANGE_PASSWORD_LOGIN
error.
If
disconnect_on_expired_password
is disabled, the server puts the client in sandbox mode.
The preceding client and server settings apply only for accounts with expired passwords. If a client connects using a nonexpired password, the server handles the client normally.
When a client connects to the MySQL server, the server uses the
user name provided by the client and the client host to select the
appropriate account row from the mysql.user
table. The server then authenticates the client, determining from
the account row which authentication plugin applies for the
client:
If the account row specifies a plugin, the server invokes it to authenticate the user. If the server cannot find the plugin, an error occurs.
If the 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.
As of MySQL 5.7.2, the server requires the plugin value to be
nonempty, and as of 5.7.5, support for
mysql_old_password
is removed.
The plugin returns a status to the server indicating whether the user is permitted to connect.
Pluggable authentication enables two important capabilities:
External authentication:
Pluggable authentication makes it possible for clients to
connect to the MySQL server with credentials that are
appropriate for authentication methods other than native
authentication based on passwords stored in the
mysql.user
table. For example, plugins can
be created to use external authentication methods such as PAM,
Windows login IDs, LDAP, or Kerberos.
Proxy users: If a user is permitted to connect, an authentication plugin can return to the server a user name different from the name of the connecting user, to indicate that the connecting user is a proxy for another user. While the connection lasts, the proxy user is treated, for purposes of access control, as having the privileges of a different user. In effect, one user impersonates another. For more information, see Section 6.3.9, “Proxy Users”.
Several authentication plugins are available in MySQL:
Plugins that perform native authentication that matches the
password against the Password
column of the
account row. The mysql_native_password
plugin implements authentication based on the native password
hashing method. The mysql_old_password
plugin implements native authentication based on the older
(pre-4.1) password hashing method (and is deprecated and
removed in MySQL 5.7.5). See
Section 6.4.1.1, “The Native Authentication Plugin”, and
Section 6.4.1.2, “The Old Native Authentication Plugin”. Native
authentication using mysql_native_password
is the default for new accounts, unless the
default_authentication_plugin
system
variable is set otherwise.
A plugin that performs authentication using SHA-256 password
hashing. This plugin matches the password against the
authentication_string
column of the account
row. This is stronger encryption than that available with
native authentication. See
Section 6.4.1.4, “The SHA-256 Authentication Plugin”.
A plugin prevents all client connections to any account that uses it. Use cases for such a plugin includes accounts that must be able to execute stored programs and views with elevated privileges without exposing those privileges to ordinary users, and proxy accounts that should never permit direct login. See Section 6.4.1.7, “The No-Login Authentication Plugin”.
A client-side plugin that sends the password to the server without hashing or encryption. This plugin can be used by server-side plugins that require access to the password exactly as provided by the client user. See Section 6.4.1.8, “The Cleartext Client-Side Authentication Plugin”.
A plugin that authenticates clients that connect from the local host through the Unix socket file. See Section 6.4.1.9, “The Socket Peer-Credential Authentication Plugin”.
A test plugin that authenticates using MySQL native authentication. This plugin is intended for testing and development purposes, and as an example of how to write an authentication plugin. See Section 6.4.1.10, “The Test Authentication Plugin”.
For information about current restrictions on the use of pluggable authentication, including which connectors support which plugins, see Section C.9, “Restrictions on Pluggable Authentication”.
Third-party connector developers should read that section to determine the extent to which a connector can take advantage of pluggable authentication capabilities and what steps to take to become more compliant.
If you are interested in writing your own authentication plugins, see Section 25.2.4.9, “Writing Authentication Plugins”.
This section provides general instructions for installing and using authentication plugins.
In general, pluggable authentication uses corresponding plugins on the server and client sides, so you use a given authentication method like this:
On the server host, install the library containing the appropriate server plugin, if necessary, so that the server can use it to authenticate client connections. Similarly, on each client host, install the library containing the appropriate client plugin for use by client programs.
Create MySQL accounts that specify use of the plugin for authentication.
When a client connects, the server plugin tells the client program which client plugin to use for authentication.
The instructions here use an example authentication plugin included in MySQL distributions (see Section 6.4.1.10, “The Test Authentication Plugin”). The procedure is similar for other authentication plugins; substitute the appropriate plugin and file names.
The example authentication plugin has these characteristics:
The server-side plugin name is
test_plugin_server
.
The client-side plugin name is
auth_test_plugin
.
Both plugins are located in the shared library object file
named auth_test_plugin.so
in the plugin
directory (the directory named by the
plugin_dir
system variable).
The file name suffix might differ on your system.
Install and use the example authentication plugin as follows:
Make sure that the plugin library is installed on the server and client hosts.
Install the server-side test plugin at server startup or at runtime:
To install the plugin at startup, use the
--plugin-load
option. With
this plugin-loading method, the option must be given each
time you start the server. For example, use these lines in
a my.cnf
option file:
[mysqld] plugin-load=test_plugin_server=auth_test_plugin.so
To install the plugin at runtime, use the
INSTALL PLUGIN
statement:
mysql> INSTALL PLUGIN test_plugin_server SONAME 'auth_test_plugin.so';
This installs the plugin permanently and need be done only once.
Verify that the plugin is installed. For example, use
SHOW PLUGINS
:
mysql> SHOW PLUGINS\G
...
*************************** 21. row ***************************
Name: test_plugin_server
Status: ACTIVE
Type: AUTHENTICATION
Library: auth_test_plugin.so
License: GPL
For other ways to check the plugin, see Section 5.1.8.2, “Obtaining Server Plugin Information”.
To specify that a MySQL user must be authenticated using a
specific server plugin, name the plugin in the
IDENTIFIED WITH
clause of the
CREATE USER
statement that
creates the user:
CREATE USER 'testuser'@'localhost' IDENTIFIED WITH test_plugin_server;
Connect to the server using a client program. The test plugin
authenticates the same way as native MySQL authentication, so
provide the usual --user
and
--password
options that you
normally use to connect to the server. For example:
shell> mysql --user=your_name
--password=your_pass
For connections by testuser
, the server
sees that the account must be authenticated using the
server-side plugin named test_plugin_server
and communicates to the client program which client-side
plugin it must use—in this case,
auth_test_plugin
.
In the case that the account uses the authentication method
that is the default for both the server and the client
program, the server need not communicate to the client which
plugin to use, and a round trip in client/server negotiation
can be avoided. This is true for accounts that use native
MySQL authentication
(mysql_native_password
).
The
--default-auth=
option can be specified on the mysql
command line as a hint about which client-side plugin the
program can expect to use, although the server will override
this if the user account requires a different plugin.
plugin_name
If the client program does not find the plugin, specify a
--plugin-dir=
option to indicate where the plugin is located.
dir_name
If you start the server with the
--skip-grant-tables
option,
authentication plugins are not used even if loaded because the
server performs no client authentication and permits any client
to connect. Because this is insecure, you might want to use
--skip-grant-tables
in
conjunction with
--skip-networking
to prevent
remote clients from connecting.
Authentication to the MySQL server occurs by means of authentication plugins. The plugin that authenticates a given connection may request that the connecting (external) user be treated as a different user for privilege-checking purposes. This enables the external user to be a proxy for the second user; that is, to have the privileges of the second user:
The external user is a “proxy user” (a user who can impersonate or become known as another user).
The second user is a “proxied user” (a user whose identity can be taken on by a proxy user).
This section describes how the proxy user capability works. For general information about authentication plugins, see Section 6.3.8, “Pluggable Authentication”. For information about specific plugins, see Section 6.4.1, “Authentication Plugins”. For information about writing authentication plugins that support proxy users, see Section 25.2.4.9.4, “Implementing Proxy User Support in Authentication Plugins”.
For proxying to occur for a given authentication plugin, these conditions must be satisfied:
A proxy user account must be set up to be authenticated by the
plugin. Use the CREATE USER
statement to associate an account with a plugin, or
ALTER USER
to change its
plugin.
For a client connecting to the proxy account to be treated as a proxy user, the plugin must return a user name different from the client user name, to indicate the user name for the proxied account.
The proxy user account must have the
PROXY
privilege for the proxied
account. Use the GRANT
statement for this.
The proxy mechanism permits mapping only the client user name to the proxied user name. There is no provision for mapping host names. When a connecting client matches a proxy account, the server attempts to match the proxied account using the user name returned by the authentication plugin and the host name of the proxy account.
Consider the following definitions:
-- create proxy user CREATE USER 'employee_ext'@'localhost' IDENTIFIED WITH my_auth_plugin AS 'my_auth_string'; -- create proxied user CREATE USER 'employee'@'localhost' IDENTIFIED BY 'employee_pass'; -- grant PROXY privilege for proxy user to proxied user GRANT PROXY ON 'employee'@'localhost' TO 'employee_ext'@'localhost';
When a client connects as employee_ext
from the
local host, MySQL uses my_auth_plugin
to
perform authentication. Suppose that
my_auth_plugin
returns a user name of
employee
to the server, based on the content of
'my_auth_string'
and perhaps by consulting some
external authentication system. The name
employee
differs from
employee_ext
, so returning
employee
serves as a request to the server to
treat the employee_ext
client, for purposes of
privilege checking, as the employee
local user.
In this case, employee_ext
is the proxy user
and employee
is the proxied user.
The server verifies that proxy authentication for
employee
is possible for the
employee_ext
user by checking whether
employee_ext
(the proxy user) has the
PROXY
privilege for
employee
(the proxied user). If this privilege
has not been granted, an error occurs.
When proxying occurs, the USER()
and
CURRENT_USER()
functions can be used to see the
difference between the connecting user (the proxy user) and the
account whose privileges apply during the current session (the
proxied user). For the example just described, those functions
return these values:
mysql> SELECT USER(), CURRENT_USER();
+------------------------+--------------------+
| USER() | CURRENT_USER() |
+------------------------+--------------------+
| employee_ext@localhost | employee@localhost |
+------------------------+--------------------+
In the CREATE USER
statement that
creates the proxy user account, the IDENTIFIED
WITH
clause that names the authentication plugin is
optionally followed by an AS
'
clause
specifying a string that the server passes to the plugin when the
user connects. If present, the string provides information that
helps the plugin determine how to map the external client user
name to a proxied user name. It is up to each plugin whether it
requires the auth_string
'AS
clause. If so, the format of
the authentication string depends on how the plugin intends to use
it. Consult the documentation for a given plugin for information
about the authentication string values it accepts.
Some authentication plugins implement proxy user mapping for
themselves. As of MySQL 5.7.7, the MySQL server itself can map
proxy users according to granted proxy privileges. If the
check_proxy_users
system
variable is enabled, the server performs proxy user mapping for
any authentication plugins that request it:
By default,
check_proxy_users
is
disabled, so the server performs no proxy user mapping even
for authentication plugins that request it.
With check_proxy_users
enabled, it may also be necessary to enable plugin-specific
system variables to take advantage of server proxy user
mapping support:
For the mysql_native_password
plugin,
enable
mysql_native_password_proxy_users
.
For the sha256_password
plugin,
enable
sha256_password_proxy_users
.
Proxy user mapping performed by the server is subject to some restrictions:
The server will not proxy to or from an anonymous user, even
if the associated PROXY
privilege is granted.
When a single account has been granted proxy privileges for more than one account, server proxy user mapping is nondeterministic. Therefore, granting proxy privileges for multiple accounts to a single account is discouraged.
The PROXY
privilege is needed to
enable an external user to connect as and have the privileges of
another user. To grant this privilege, use the
GRANT
statement. For example:
GRANT PROXY ON 'proxied_user
' TO 'proxy_user
';
The statement creates a row in the
mysql.proxies_priv
grant table.
At connection time, proxy_user
must
represent a valid externally authenticated MySQL user, and
proxied_user
must represent a valid
locally authenticated user. Otherwise, the connection attempt
fails.
The corresponding REVOKE
syntax
is:
REVOKE PROXY ON 'proxied_user
' FROM 'proxy_user
';
MySQL GRANT
and
REVOKE
syntax extensions work as
usual. For example:
GRANT PROXY ON 'a' TO 'b', 'c', 'd'; GRANT PROXY ON 'a' TO 'd' WITH GRANT OPTION; GRANT PROXY ON 'a' TO ''@''; REVOKE PROXY ON 'a' FROM 'b', 'c', 'd';
In the preceding example, ''@''
is the
default proxy user and means “any user.” Default
proxy user are discussed in
Default Proxy Users.
The PROXY
privilege can be
granted in these cases:
By a user that has GRANT PROXY ... WITH GRANT
OPTION
for
proxied_user
.
By proxied_user
for itself: The
value of USER()
must exactly match
CURRENT_USER()
and
proxied_user
, for both the user
name and host name parts of the account name.
The initial root
account created during MySQL
installation has the
PROXY ... WITH GRANT
OPTION
privilege for ''@''
, that
is, for all users and all hosts. This enables
root
to set up proxy users, as well as to
delegate to other accounts the authority to set up proxy users.
For example, root
can do this:
CREATE USER 'admin'@'localhost' IDENTIFIED BY 'test'; GRANT PROXY ON ''@'' TO 'admin'@'localhost' WITH GRANT OPTION;
Those statements create an admin
user that
can manage all GRANT PROXY
mappings. For
example, admin
can do this:
GRANT PROXY ON sally TO joe;
To specify that some or all users should connect using a given
plugin, create a “blank” MySQL user, set it up to
use that plugin for authentication, and let the plugin return
the real authenticated user name (if different from the blank
user). For example, suppose that there exists a plugin named
ldap_auth
that implements LDAP
authentication, and that maps connecting users onto either a
developer or manager account. To set up proxying of users onto
these accounts, use the following statements:
-- create default proxy user CREATE USER ''@'' IDENTIFIED WITH ldap_auth AS 'O=Oracle, OU=MySQL'; -- create proxied users CREATE USER 'developer'@'localhost' IDENTIFIED BY 'developer_pass'; CREATE USER 'manager'@'localhost' IDENTIFIED BY 'manager_pass'; -- grant PROXY privilege for default proxy user to proxied users GRANT PROXY ON 'manager'@'localhost' TO ''@''; GRANT PROXY ON 'developer'@'localhost' TO ''@'';
Now assume that a client tries to connect as follows:
mysql --user=myuser --password='myuser_pass' ...
The server will not find myuser
defined as a
MySQL user. But because there is a blank user account
(''@''
), that matches the client user name
and host name, the server authenticates the client against that
account: The server invokes the ldap_auth
authentication plugin and passes myuser
and
myuser_pass
to it as the user name and
password.
If the ldap_auth
plugin finds in the LDAP
directory that myuser_pass
is not the correct
password for myuser
, authentication fails and
the server rejects the connection.
If the password is correct and ldap_auth
finds that myuser
is a developer, it returns
the user name developer
to the MySQL server,
rather than myuser
. Returning a user name
different from the client user name of myuser
signals to the server that it should treat
myuser
as a proxy. The server verifies that
''@''
can authenticate as
developer
(because it has the
PROXY
privilege to do so) and
accepts the connection. The session proceeds with
myuser
having the privileges of
developer
, the proxied user. (These
privileges should be set up by the DBA using
GRANT
statements, not shown.) The
USER()
and
CURRENT_USER()
functions return
these values:
mysql> SELECT USER(), CURRENT_USER();
+------------------+---------------------+
| USER() | CURRENT_USER() |
+------------------+---------------------+
| myuser@localhost | developer@localhost |
+------------------+---------------------+
If the plugin instead finds in the LDAP directory that
myuser
is a manager, it returns
manager
as the user name and the session
proceeds with myuser
having the privileges of
manager
.
mysql> SELECT USER(), CURRENT_USER();
+------------------+-------------------+
| USER() | CURRENT_USER() |
+------------------+-------------------+
| myuser@localhost | manager@localhost |
+------------------+-------------------+
For simplicity, external authentication cannot be multilevel:
Neither the credentials for developer
nor
those for manager
are taken into account in
the preceding example. However, they are still used if a client
tries to connect and authenticate directly as the
developer
or manager
account, which is why those accounts should be assigned
passwords.
If you intend to create a default proxy user, check for other existing “match any user” accounts that take precedence over the default proxy user and thus prevent that user from working as intended.
In the preceding discussion, the default proxy user account has
''
in the host part, which matches any host.
If you set up a default proxy user, take care to also check
whether nonproxy accounts exist with the same user part and
'%'
in the host part, because
'%'
also matches any host, but has precedence
over ''
by the rules that the server uses to
sort account rows internally (see
Section 6.2.4, “Access Control, Stage 1: Connection Verification”).
Suppose that a MySQL installation includes these two accounts:
-- create default proxy user CREATE USER ''@'' IDENTIFIED WITH some_plugin AS 'some_auth_string'; -- create anonymous user CREATE USER ''@'%' IDENTIFIED BY 'some_password';
The first account (''@''
) is intended as the
default proxy user, used to authenticate connections for users
who do not otherwise match a more-specific account. The second
account (''@'%'
) is an anonymous-user
account, which might have been created, for example, to enable
users without their own account to connect anonymously.
Both accounts have the same user part (''
),
which matches any user. And each account has a host part that
matches any host. Nevertheless, there is a priority in account
matching because the matching rules sort a host of
'%'
ahead of ''
. For
accounts that do not match any more-specific account, the server
attempts to authenticate them against ''@'%'
(the anonymous user) rather than ''@''
(the
default proxy user). The result is that the default proxy
account is never used.
To avoid this problem, use one of the following strategies:
Remove the anonymous account so that it does not conflict with the default proxy user. This might be a good idea anyway if you want to associate every connection with a named user.
Use a more-specific default proxy user that matches ahead of
the anonymous user. For example, to permit only
localhost
proxy connections, use
''@'localhost'
:
CREATE USER ''@'localhost' IDENTIFIED WITH some_plugin AS 'some_auth_string';
In addition, modify any GRANT PROXY
statements to name ''@'localhost'
rather
than ''@''
as the proxy user.
Be aware that this strategy prevents anonymous-user
connections from localhost
.
Create multiple proxy users, one for local connections and one for “everything else” (remote connections). This can be useful particularly when local users should have different privileges from remote users.
Create the proxy users:
-- create proxy user for local connections CREATE USER ''@'localhost' IDENTIFIED WITH some_plugin AS 'some_auth_string'; -- create proxy user for remote connections CREATE USER ''@'%' IDENTIFIED WITH some_plugin AS 'some_auth_string';
Create the proxied users:
-- create proxied user for local connections CREATE USER 'developer'@'localhost' IDENTIFIED BY 'some_password'; -- create proxied user for remote connections CREATE USER 'developer'@'%' IDENTIFIED BY 'some_password';
Grant the proxy privilege to each proxy user for the corresponding proxied user:
GRANT PROXY ON 'developer'@'localhost' TO ''@'localhost'; GRANT PROXY ON 'developer'@'%' TO ''@'%';
Finally, grant appropriate privileges to the local and remote proxied users (not shown).
Assume that the
some_plugin
/'some_auth_string'
combination causes some_plugin
to map the
client user name to developer
. Local
connections match the ''@'localhost'
proxy user, which maps to the
'developer'@'localhost'
proxied user.
Remote connections match the ''@'%'
proxy
user, which maps to the 'developer'@'%'
proxied user.
Two system variables help trace the proxy login process:
proxy_user
: This value is
NULL
if proxying is not used. Otherwise,
it indicates the proxy user account. For example, if a
client authenticates through the ''@''
proxy account, this variable is set as follows:
mysql> SELECT @@proxy_user;
+--------------+
| @@proxy_user |
+--------------+
| ''@'' |
+--------------+
external_user
: Sometimes
the authentication plugin may use an external user to
authenticate to the MySQL server. For example, when using
Windows native authentication, a plugin that authenticates
using the windows API does not need the login ID passed to
it. However, it still uses a Windows user ID to
authenticate. The plugin may return this external user ID
(or the first 512 UTF-8 bytes of it) to the server using the
external_user
read-only session variable.
If the plugin does not set this variable, its value is
NULL
.
As of version 5.7.6, MySQL supports locking and unlocking user
accounts using the ACCOUNT LOCK
and
ACCOUNT UNLOCK
clauses for the
CREATE USER
and
ALTER USER
statements:
When used with CREATE USER
,
these clauses specify the initial locking state for a new
account. In the absence of either clause, the account is
created in an unlocked state.
When used with ALTER USER
,
these clauses specify the new locking state for an existing
account. In the absence of either clause, the account locking
state remains unchanged.
Account locking state is recorded in the
account_locked
column of the
mysql.user
table. The output from
SHOW CREATE USER
indicates whether
an account is locked or unlocked.
If a client attempts to connect to a locked account, the attempt
fails. The server increments the
Locked_connects
status variable
that indicates the number of attempts to connect to a locked
account, returns an
ER_ACCOUNT_HAS_BEEN_LOCKED
error,
and writes a message to the error log:
Access denied for user 'user_name
'@'host_name
'. Account is locked.
Locking an account does not affect being able to connect using a
proxy user that assumes the identity of the locked account. It
also does not affect the ability to execute stored programs or
views that have a DEFINER
clause naming the
locked account. That is, the ability to use a proxied account or
stored programs or views is not affected by locking the account.
The account-locking capability depends on the presence of the
account_locked
column in the
mysql.user
table. For upgrades to MySQL 5.7.6
and later from older versions, run
mysql_upgrade to ensure that this column
exists. For nonupgraded installations that have no
account_locked
column, the server treats all
accounts as unlocked, and using the ACCOUNT
LOCK
or ACCOUNT UNLOCK
clauses
produces an error.
With an unencrypted connection between the MySQL client and the server, someone with access to the network could watch all your traffic and inspect the data being sent or received between client and server.
When you must move information over a network in a secure fashion, an unencrypted connection is unacceptable. To make any kind of data unreadable, use encryption. Encryption algorithms must include security elements to resist many kinds of known attacks such as changing the order of encrypted messages or replaying data twice.
MySQL supports secure (encrypted) connections between clients and the server using the TLS (Transport Layer Security) protocol. TLS is sometimes referred to as SSL (Secure Sockets Layer) but MySQL does not actually use the SSL protocol for secure connections because it provides weak encryption (see Section 6.3.11.3, “Secure Connection Protocols and Ciphers”).
TLS uses encryption algorithms to ensure that data received over a public network can be trusted. It has mechanisms to detect data change, loss, or replay. TLS also incorporates algorithms that provide identity verification using the X509 standard.
X509 makes it possible to identify someone on the Internet. In basic terms, there should be some entity called a “Certificate Authority” (or CA) that assigns electronic certificates to anyone who needs them. Certificates rely on asymmetric encryption algorithms that have two encryption keys (a public key and a secret key). A certificate owner can present the certificate to another party as proof of identity. A certificate consists of its owner's public key. Any data encrypted using this public key can be decrypted only using the corresponding secret key, which is held by the owner of the certificate.
For more information about TLS, SSL, X509, encryption, or public-key cryptography, perform an Internet search for the keywords in which you are interested.
MySQL can be compiled for secure-connection support using OpenSSL or yaSSL. For a comparison of the two packages, see Section 6.3.11.1, “OpenSSL Versus yaSSL” For information about the encryption protocols and ciphers each package supports, see Section 6.3.11.3, “Secure Connection Protocols and Ciphers”.
MySQL performs encryption on a per-connection basis, and use of
encryption can be optional or mandatory. This enables you to
choose an encrypted or unencrypted connection according to the
requirements of individual applications. For information on how to
require users to use encrypted connections, see the discussion of
the REQUIRE
clause of the
CREATE USER
statement in
Section 13.7.1.2, “CREATE USER Syntax”. See also the description of the
require_secure_transport
system
variable at Section 5.1.4, “Server System Variables”
Several improvements were made to secure-connection support in MySQL 5.7. The following timeline summarizes the changes:
5.7.3: On the client side, an explicit
--ssl
option is no longer
advisory but prescriptive. Given a server enabled to support
secure connections, a client program can require a secure
conection by specifying only the
--ssl
option. The connection
attempt fails if a secure connection cannot be established.
Other --ssl-
options on the client side mean that a secure connection is
advisory (the connection attempt falls back to an unencrypted
connection if a secure connection cannot be established).
xxx
5.7.5: The server-side --ssl
option value is enabled by default.
For servers compiled using OpenSSL, the
auto_generate_certs
and
sha256_password_auto_generate_rsa_keys
system variables are available to enable autogeneration and
autodiscovery of SSL/RSA certificate and key files at startup.
For certificate and key autodiscovery, if
--ssl
is enabled and other
--ssl-
options
are not given to configure secure connections explicitly, the
server attempts to enable support for secure connections
automatically at startup if it discovers the requisite
certificate and key files in the data directory.
xxx
5.7.6: The mysql_ssl_rsa_setup utility is
available to make it easier to manually generate SSL/RSA
certificate and key files. Autodiscovery of SSL/RSA files at
startup is expanded to apply to all servers, whether compiled
using OpenSSL or yaSSL. (This means that
auto_generate_certs
need not
be enabled for autodiscovery to occur.)
If the server discovers at startup that the CA certificate is self-signed, it writes a warning to its error log. (The certificate will be self-signed if created automatically by the server or manually using mysql_ssl_rsa_setup.)
5.7.7: The C client library attempts to establish a secure connection by default whenever the server supports secure connections. This affects client programs as follows:
In the absence of an --ssl
option, the client falls back to an unencrypted connection
if a secure connection cannot be established.
To require a secure connection and fail if one cannot be
established, invoke the client with an explicit
--ssl
option or a synonym
(--ssl=1
,
--enable-ssl
).
To use an unencrypted connection, invoke the client with
an --ssl=0
option or a
synonym
(--skip-ssl
,
--disable-ssl
).
This change also affects subsequent releases of MySQL Connectors that are based on the C client library: Connector/C, Connector/C++, and Connector/ODBC.
5.7.8: The
require_secure_transport
system variable is available to control whether client
connections to the server must use some form of secure
transport.
5.7.10: TLS protocol support is extended from TLSv1 to also
include TLSv1.1 and TLSv1.2. The
tls_version
system variable
on the server side and
--tls-version
option on the
client side enable the level of support to be selected. See
Section 6.3.11.3, “Secure Connection Protocols and Ciphers”.
5.7.11: MySQL client programs support an
--ssl-mode
option that enables
you to specify the security state of the connection to the
server. The --ssl-mode
option
comprises the capabilities of the client-side
--ssl
and
--ssl-verify-server-cert
options. Consequently, both of those options are deprecated
and will be removed in a future MySQL release.
Secure connections are available through the MySQL C API using the
mysql_ssl_set()
and
mysql_options()
functions. See
Section 24.8.7.73, “mysql_ssl_set()”, and
Section 24.8.7.50, “mysql_options()”.
Replication uses the C API, so secure connections can be used between master and slave servers. See Section 17.3.7, “Setting Up Replication to Use Secure Connections”.
It is also possible to connect securely from within an SSH connection to the MySQL server host. For an example, see Section 6.3.13, “Connecting to MySQL Remotely from Windows with SSH”.
MySQL can be compiled using OpenSSL or yaSSL, both of which enable secure conections based on the OpenSSL API:
MySQL Enterprise Edition binary distributions are compiled using OpenSSL. It is not possible to use yaSSL with MySQL Enterprise Edition.
MySQL Community Edition binary distributions are compiled using yaSSL.
MySQL Community Edition source distributions can be compiled using either OpenSSL or yaSSL (see Section 6.3.11.2, “Building MySQL with Support for Secure Connections”).
OpenSSL and yaSSL offer the same basic functionality, but MySQL distributions compiled using OpenSSL have additional features:
OpenSSL supports a wider range of encryption ciphers from
which to choose for the
--ssl-cipher
option. OpenSSL
supports the --ssl-capath
,
--ssl-crl
, and
--ssl-crlpath
options. See
Section 6.3.11.5, “Command Options for Secure Connections”.
Accounts that authenticate using the
sha256_password
plugin can use RSA key
files for secure password exchange over unencrypted
connections. See
Section 6.4.1.4, “The SHA-256 Authentication Plugin”.
The server can automatically generate missing SSL and RSA certificate and key files at startup. See Section 6.3.12.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
OpenSSL supports more encryption modes for the
AES_ENCRYPT()
and
AES_DECRYPT()
functions. See
Section 12.13, “Encryption and Compression Functions”
Certain OpenSSL-related system and status variables are present only if MySQL was compiled using OpenSSL:
auto_generate_certs
(added
in MySQL 5.7.5)
sha256_password_auto_generate_rsa_keys
(added in MySQL 5.7.5)
To determine whether your server was compiled using OpenSSL, test the existence of any of those variables. For example, this statement returns a row if OpenSSL was used and an empty result if yaSSL was used:
SHOW STATUS LIKE 'Rsa_public_key';
Such tests assume that your server version is not older than the
first appearance of the variable tested. For example, you cannot
test for auto_generate_certs
before MySQL 5.7.6.
To use SSL connections between the MySQL server and client programs, your system must support either OpenSSL or yaSSL:
MySQL Enterprise Edition binary distributions are compiled using OpenSSL. It is not possible to use yaSSL with MySQL Enterprise Edition.
MySQL Community Edition binary distributions are compiled using yaSSL.
MySQL Community Edition source distributions can be compiled using either OpenSSL or yaSSL.
If you compile MySQL from a source distribution, CMake configures the distribution to use yaSSL by default. To compile using OpenSSL instead, use this procedure:
Ensure OpenSSL 1.0.1 or higher is installed on your system. To obtain OpenSSL, visit http://www.openssl.org.
If the installed OpenSSL version is lower than 1.0.1, CMake produces an error at MySQL configuration time.
To use OpenSSL, add the
-DWITH_SSL=system
option to
the CMake command you normally use to
configure the MySQL source distribution. For example:
shell> cmake . -DWITH_SSL=system
That command configures the distribution to use the installed OpenSSL library. Alternatively, to explicitly specify the path name to the OpenSSL installation, use the following syntax. This can be useful if you have multiple versions of OpenSSL installed, to prevent CMake from choosing the wrong one:
shell> cmake . -DWITH_SSL=path_name
Compile and install the distribution.
To check whether a mysqld server supports
secure connections, examine the value of the
have_ssl
system variable:
mysql> SHOW VARIABLES LIKE 'have_ssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl | YES |
+---------------+-------+
If the value is YES
, the server supports
secure connections. If the value is DISABLED
,
the server is capable of supporting secure connections but was
not started with the appropriate
--ssl-
options to
enable secure connections to be used; see
Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
xxx
To determine whether a server was compiled using OpenSSL or yaSSL, check the existence of any of the system or status variables that are present only for OpenSSL. See Section 6.3.11.1, “OpenSSL Versus yaSSL”
To determine which encryption protocol and cipher are in use for
an encrypted connection, use the following statements to check
the values of the Ssl_version
and Ssl_cipher
status
variables:
mysql>SHOW SESSION STATUS LIKE 'Ssl_version';
+---------------+-------+ | Variable_name | Value | +---------------+-------+ | Ssl_version | TLSv1 | +---------------+-------+ mysql>SHOW SESSION STATUS LIKE 'Ssl_cipher';
+---------------+---------------------------+ | Variable_name | Value | +---------------+---------------------------+ | Ssl_cipher | DHE-RSA-AES128-GCM-SHA256 | +---------------+---------------------------+
If the connection is not encrypted, both variables have an empty value.
MySQL supports encrypted connections using TLS protocols:
When compiled using OpenSSL 1.0.1 or higher, MySQL supports the TLSv1, TLSv1.1, and TLSv1.2 protocols.
When compiled using the bundled version of yaSSL, MySQL supports the TLSv1 and TLSv1.1 protocols.
The value of the tls_version
system variable determines which protocols the server is
permitted to use from those that are available. The
tls_version
value is a
comma-separated list containing one or more of these protocols
(not case sensitive): TLSv1, TLSv1.1, TLSv1.2. By default, this
variable lists all protocols supported by the SSL library used
to compile MySQL (TLSv1,TLSv1.1,TLSv1.2
for
OpenSSL, TLSv1,TLSv1.1
for yaSSL). To change
the value of tls_version
, set
it at server startup. To determine its value at runtime, use
this statement:
mysql> SHOW GLOBAL VARIABLES LIKE 'tls_version';
+---------------+-----------------------+
| Variable_name | Value |
+---------------+-----------------------+
| tls_version | TLSv1,TLSv1.1,TLSv1.2 |
+---------------+-----------------------+
For client programs, the
--tls-version
option enables
specifying the TLS protocols permitted per client invocation.
The value format is the same as for
tls_version
.
By default, MySQL attempts to use the highest TLS protocol
version available, depending on which SSL library was used to
compile the server and client, which key size is used, and
whether the server or client are restricted from using some
protocols; for example, by means of
tls_version
/--tls-version
:
If the server and client are compiled using OpenSSL, TLSv1.2 is used if possible.
If either or both the server and client are compiled using yaSSL, TLSv1.1 is used if possible.
TLSv1.2 does not work with all ciphers that have a key size
of 512 bits or less. To use this protocol with such a key,
use --ssl-cipher
to specify
the cipher name explicitly:
AES128-SHA AES128-SHA256 AES256-SHA AES256-SHA256 CAMELLIA128-SHA CAMELLIA256-SHA DES-CBC3-SHA DHE-RSA-AES256-SHA RC4-MD5 RC4-SHA SEED-SHA
For better security, use a certificate with an RSA key size of of 2048 bits or more.
Prior to MySQL 5.7.10, MySQL supports only TLSv1, for both OpenSSL and yaSSL, and no system variable or client option exist for specifying which TLS protocols to permit.
If the server and client protocol capabilities have no protocol
in common, the server terminates the connection request. For
example, if the server is configured with
tls_version=TLSv1.1,TLSv1.2
,
connection attempts will fail for clients invoked with
--tls-version=TLSv1
, and for
older clients that do not support the
--tls-version
option and
implicitly support only TLSv1.
To determine which ciphers a given server supports, use the
following statement to check the value of the
Ssl_cipher_list
status
variable:
SHOW SESSION STATUS LIKE 'Ssl_cipher_list';
As of MySQL 5.7.10, order of ciphers passed by MySQL to the SSL library is significant. More secure ciphers are mentioned first in the list, and the first cipher supported by the provided certificate is selected.
The set of available ciphers depends on your MySQL version and whether MySQL was compiled using OpenSSL or yaSSL, and (for OpenSSL) the library version used to compile MySQL.
MySQL passes this cipher list to OpenSSL:
ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES128-SHA256 ECDHE-RSA-AES128-SHA256 ECDHE-ECDSA-AES256-SHA384 ECDHE-RSA-AES256-SHA384 DHE-RSA-AES128-GCM-SHA256 DHE-DSS-AES128-GCM-SHA256 DHE-RSA-AES128-SHA256 DHE-DSS-AES128-SHA256 DHE-DSS-AES256-GCM-SHA384 DHE-RSA-AES256-SHA256 DHE-DSS-AES256-SHA256 ECDHE-RSA-AES128-SHA ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES256-SHA ECDHE-ECDSA-AES256-SHA DHE-DSS-AES128-SHA DHE-RSA-AES128-SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA AES128-GCM-SHA256 DH-DSS-AES128-GCM-SHA256 ECDH-ECDSA-AES128-GCM-SHA256 AES256-GCM-SHA384 DH-DSS-AES256-GCM-SHA384 ECDH-ECDSA-AES256-GCM-SHA384 AES128-SHA256 DH-DSS-AES128-SHA256 ECDH-ECDSA-AES128-SHA256 AES256-SHA256 DH-DSS-AES256-SHA256 ECDH-ECDSA-AES256-SHA384 AES128-SHA DH-DSS-AES128-SHA ECDH-ECDSA-AES128-SHA AES256-SHA DH-DSS-AES256-SHA ECDH-ECDSA-AES256-SHA DHE-RSA-AES256-GCM-SHA384 DH-RSA-AES128-GCM-SHA256 ECDH-RSA-AES128-GCM-SHA256 DH-RSA-AES256-GCM-SHA384 ECDH-RSA-AES256-GCM-SHA384 DH-RSA-AES128-SHA256 ECDH-RSA-AES128-SHA256 DH-RSA-AES256-SHA256 ECDH-RSA-AES256-SHA384 ECDHE-RSA-AES128-SHA ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES256-SHA ECDHE-ECDSA-AES256-SHA DHE-DSS-AES128-SHA DHE-RSA-AES128-SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA AES128-SHA DH-DSS-AES128-SHA ECDH-ECDSA-AES128-SHA AES256-SHA DH-DSS-AES256-SHA ECDH-ECDSA-AES256-SHA DH-RSA-AES128-SHA ECDH-RSA-AES128-SHA DH-RSA-AES256-SHA ECDH-RSA-AES256-SHA DES-CBC3-SHA
MySQL passes this cipher list to yaSSL:
DHE-RSA-AES256-SHA DHE-RSA-AES128-SHA AES128-RMD DES-CBC3-RMD DHE-RSA-AES256-RMD DHE-RSA-AES128-RMD DHE-RSA-DES-CBC3-RMD AES256-SHA RC4-SHA RC4-MD5 DES-CBC3-SHA DES-CBC-SHA EDH-RSA-DES-CBC3-SHA EDH-RSA-DES-CBC-SHA AES128-SHA:AES256-RMD
As of MySQL 5.7.10, these cipher restrictions are in place:
The following ciphers are permanently restricted:
!DHE-DSS-DES-CBC3-SHA !DHE-RSA-DES-CBC3-SHA !ECDH-RSA-DES-CBC3-SHA !ECDH-ECDSA-DES-CBC3-SHA !ECDHE-RSA-DES-CBC3-SHA !ECDHE-ECDSA-DES-CBC3-SHA
The following categories of ciphers are permanently restricted:
!aNULL !eNULL !EXPORT !LOW !MD5 !DES !RC2 !RC4 !PSK !SSLv3
If the server is started using a compatible certificate that uses any of the preceding restricted ciphers or cipher categories, the server starts with support for secure connections disabled.
To enable secure connections, the proper options must be used to specify the appropriate certificate and key files. For a complete list of options related to establishment of secure connections, see Section 6.3.11.5, “Command Options for Secure Connections”.
If you need to create the required certificate and key files, see Section 6.3.12, “Creating SSL and RSA Certificates and Keys”.
To start the MySQL server so that it permits clients to connect securely, use options that identify the certificate and key files the server uses when establishing a secure connection:
--ssl-ca
identifies the
Certificate Authority (CA) certificate.
--ssl-cert
identifies the
server public key certificate. This can be sent to the
client and authenticated against the CA certificate that it
has.
--ssl-key
identifies the
server private key.
For example, start the server with these lines in the
my.cnf
file, changing the file names as
necessary:
[mysqld] ssl-ca=ca.pem ssl-cert=server-cert.pem ssl-key=server-key.pem
Each option names a file in PEM format. If you have a MySQL
source distribution, you can test your setup using the
demonstration certificate and key files in its
mysql-test/std_data
directory.
As of MySQL 5.7.5, the server-side
--ssl
option value is enabled by
default. Also as of MySQL 5.7.5, MySQL servers compiled using
OpenSSL can generate missing certificate and key files
automatically at startup. See
Section 6.3.12.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
Certificate and key file autodiscovery is enabled as of MySQL
5.7.5 (for servers compiled using OpenSSL) or 5.7.6 (for servers
compiled using yaSSL). If --ssl
is enabled (possibly along with
--ssl-cipher
) and other
--ssl-
options
are not given to configure secure connections explicitly, the
server attempts to enable support for secure connections
automatically at startup:
xxx
If the server discovers valid certificate and key files
named ca.pem
,
server-cert.pem
, and
server-key.pem
in the data directory,
it enables support for secure connections by clients. (The
files need not have been autogenerated; what matters is that
they have the indicated names and are valid.)
If the server does not find valid certificate and key files in the data directory, it continues executing but does not enable secure connections.
If the server automatically enables support for secure connections, it writes a message to the error log. As of MySQL 5.7.6, if the server discovers that the CA certificate is self-signed, it writes a warning to the error log. (The certificate will be self-signed if created automatically by the server or manually using mysql_ssl_rsa_setup.)
For any certificate and key files that the server discovers and
uses automatically, it uses the file names to set the
corresponding system variables
(ssl_ca
,
ssl_cert
,
ssl_key
).
For further control over whether clients must connect securely,
use the
require_secure_transport
system
variable; see Section 5.1.4, “Server System Variables”. For
information about permitted encryption protocols and ciphers,
see Section 6.3.11.3, “Secure Connection Protocols and Ciphers”.
For client programs, options for secure connections are similar
to those used on the server side, but
--ssl-cert
and
--ssl-key
identify the client
public and private key:
--ssl-ca
identifies the
Certificate Authority (CA) certificate. This option, if
used, must specify the same certificate used by the server.
--ssl-cert
identifies the
client public key certificate.
--ssl-key
identifies the
client private key.
To connect securely to a MySQL server that supports secure
connections, the options that a client must specify depend on
the encryption requirements of the MySQL account used by the
client. (See the discussion of the REQUIRE
clause in Section 13.7.1.2, “CREATE USER Syntax”.)
Suppose that you want to connect using an account that has no
special encryption requirements or was created using a
CREATE USER
statement that
includes the REQUIRE SSL
option. As a
recommended set of secure-connection options, start the server
with at least --ssl-cert
and
--ssl-key
, and invoke the client
with --ssl-ca
. A client can
connect securely like this:
shell> mysql --ssl-ca=ca.pem
To require that a client certificate also be specified, create
the account using the REQUIRE X509
option.
Then the client must also specify the proper client key and
certificate files or the server will reject the connection:
shell>mysql --ssl-ca=ca.pem \
--ssl-cert=client-cert.pem \
--ssl-key=client-key.pem
To prevent use of encryption and override other
--ssl-
options,
invoke the client program with
xxx
--ssl=0
or a synonym
(--skip-ssl
,
--disable-ssl
):
shell> mysql --ssl=0
As of MySQL 5.7.7, client programs attempt to establish a secure connection by default whenever the server supports secure connections:
In the absence of an --ssl
option, the client falls back to an unencrypted connection
if a secure connection cannot be established.
To require a secure connection and fail if one cannot be
established, invoke the client with an explicit
--ssl
option or a synonym
(--ssl=1
,
--enable-ssl
).
To use an unencrypted connection, invoke the client with an
--ssl=0
option or a synonym
(--skip-ssl
,
--disable-ssl
).
From MySQL 5.7.3 to 5.7.6, --ssl
on the client side is prescriptive (not advisory as before MySQL
5.7.3): With --ssl
, connection
attempts fail if a secure connection cannot be established.
Before MySQL 5.7.3, --ssl
on the
client side is advisory: --ssl
permits but does not require the client to connect to the server
using encryption. Therefore, this option is not sufficient in
itself to cause a secure connection to be used. For example, if
you specify this option for a client program but the server has
not been configured to support secure connections, the client
falls back to an unencrypted connection.
For information about permitted encryption protocols and ciphers, see Section 6.3.11.3, “Secure Connection Protocols and Ciphers”.
A client can determine whether the current connection with the
server uses encryption by checking the value of the
Ssl_cipher
status variable. If
the value is empty, the connection is encrypted. Otherwise, the
connection is encrypted and the value indicates the encryption
cipher. For example:
mysql> SHOW STATUS LIKE 'Ssl_cipher';
+---------------+--------------------+
| Variable_name | Value |
+---------------+--------------------+
| Ssl_cipher | DHE-RSA-AES256-SHA |
+---------------+--------------------+
For the mysql client, an alternative is to
use the STATUS
or \s
command and check the SSL
line:
mysql> \s
...
SSL: Cipher in use is DHE-RSA-AES256-SHA
...
Or:
mysql> \s
...
SSL: Not in use
...
The C API enables application programs to use secure connections:
To establish a secure connection, use the
mysql_ssl_set()
C API
function to set the appropriate certificate options before
calling
mysql_real_connect()
. See
Section 24.8.7.73, “mysql_ssl_set()”. To require the use of a
secure connection, call
mysql_options()
with the
MYSQL_OPT_SSL_MODE
option (use
MYSQL_OPT_SSL_ENFORCE
option before MySQL
5.7.11). To establish permitted encryption protocols, call
mysql_options()
with the
MYSQL_OPT_TLS_VERSION
option.
To determine whether encryption is in use after the
connection is established, use
mysql_get_ssl_cipher()
. A
non-NULL
return value indicates an
encrypted connection and names the cipher used for
encryption. A NULL
return value indicates
that encryption is not being used. See
Section 24.8.7.34, “mysql_get_ssl_cipher()”.
Replication uses the C API, so secure connections can be used between master and slave servers. See Section 17.3.7, “Setting Up Replication to Use Secure Connections”.
This section describes options that specify whether to use secure connections and the names of certificate and key files. These options can be given on the command line or in an option file. For examples of suggested use and how to check whether a connection is secure, see Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
Table 6.8 Secure-Connection Option Summary
Format | Description | Introduced |
---|---|---|
--skip-ssl | Do not use secure connection | |
--ssl | Enable secure connection | |
--ssl-ca | Path of file that contains list of trusted SSL CAs | |
--ssl-capath | Path of directory that contains trusted SSL CA certificates in PEM format | |
--ssl-cert | Path of file that contains X509 certificate in PEM format | |
--ssl-cipher | List of permitted ciphers to use for connection encryption | |
--ssl-crl | Path of file that contains certificate revocation lists | |
--ssl-crlpath | Path of directory that contains certificate revocation list files | |
--ssl-key | Path of file that contains X509 key in PEM format | |
--ssl-mode | Security state of connection to server | 5.7.11 |
--ssl-verify-server-cert | Verify server certificate Common Name value against host name used when connecting to server | |
--tls-version | Protocols permitted for secure connections | 5.7.10 |
This option has different effects on the server and client sides.
The client-side --ssl
option is deprecated as of MySQL 5.7.11 and will be
removed in a future MySQL release. For client programs, it
is preferable to use
--ssl-mode
:
Use
--ssl-mode=REQUIRED
instead of --ssl=1
or
--enable-ssl
.
Use
--ssl-mode=DISABLED
instead of --ssl=0
,
--skip-ssl
,
or
--disable-ssl
.
No explicit --ssl-mode
option is equivalent to no explicit
--ssl
option.
The server-side --ssl
option is not deprecated.
For the MySQL server, this option specifies that the server permits but does not require secure connections. The option is enabled on the server side by default as of MySQL 5.7.5, and disabled before 5.7.5. Also as of MySQL 5.7.5, MySQL servers compiled using OpenSSL can generate missing certificate and key files automatically at startup. See Section 6.3.12.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
Certificate and key file autodiscovery is enabled as of
MySQL 5.7.5 (for servers compiled using OpenSSL) or 5.7.6
(for servers compiled using yaSSL). If
--ssl
is enabled (possibly
along with --ssl-cipher
) and
other --ssl-
options are not given to configure secure connections
explicitly, the server attempts to enable support for secure
connections automatically at startup:
xxx
If the server discovers valid certificate and key files
named ca.pem
,
server-cert.pem
, and
server-key.pem
in the data
directory, it enables support for secure connections by
clients. (The files need not have been autogenerated;
what matters is that they have the indicated names and
are valid.)
If the server does not find valid certificate and key files in the data directory, it continues executing but does not enable secure connections.
For MySQL client programs, the
--ssl
option is used as
follows:
As of MySQL 5.7.7, client programs attempt to establish a secure connection by default whenever the server supports secure connections:
In the absence of an
--ssl
option, the
client falls back to an unencrypted connection if a
secure connection cannot be established.
To require a secure connection and fail if one
cannot be established, invoke the client with an
explicit --ssl
option or a synonym
(--ssl=1
,
--enable-ssl
).
To use an unencrypted connection, invoke the client
with an --ssl=0
option or a synonym
(--skip-ssl
,
--disable-ssl
).
From MySQL 5.7.3 to 5.7.6,
--ssl
is prescriptive
(not advisory as before MySQL 5.7.3): With
--ssl
, connection
attempts fail if a secure connection cannot be
established.
Before MySQL 5.7.3,
--ssl
is advisory:
--ssl
permits but does
not require the client to connect to the server using
encryption. Therefore, this option is not sufficient in
itself to cause a secure connection to be used. For
example, if you specify this option for a client program
but the server has not been configured to support secure
connections, the client falls back to an unencrypted
connection.
--ssl
is implied by
other
--ssl-
options, as indicated in the descriptions for those
options.
xxx
If other
--ssl-
options are given in the absence of xxx
--ssl
,
the client attempts to connect securely. If the server is
configured to support secure connections, the connection
attempt fails if a secure connection cannot be established.
If the server is not configured for secure connections, the
client falls back to an unencrypted connection.
As a recommended set of options to enable secure
connections, use at least
--ssl-cert
and
--ssl-key
on the server side
and --ssl-ca
on the client
side. See Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
The --ssl
option in negated
form overrides other
--ssl-
options and indicates that encryption should
not be used. To do this, specify the
option as xxx
--ssl=0
or a
synonym
(--skip-ssl
,
--disable-ssl
).
For example, you might have options specified in the
[client]
group of your option file to use
secure connections by default when you invoke MySQL client
programs. To use an unencrypted connection instead, invoke
the client program with
--ssl=0
on
the command line to override the options in the option file.
To require use of secure connections for a MySQL account,
use CREATE USER
to create the
account with at least a REQUIRE SSL
clause, or use ALTER USER
for
an existing account to add a REQUIRE
clause. Connections for the account will be rejected unless
MySQL supports secure connections and the server and client
have been started with the proper secure-connection options.
The REQUIRE
clause permits other
encryption-related options, which can be used to enforce
stricter requirements than REQUIRE SSL
.
For additional details about which command options may or
must be specified by clients that connect using accounts
configured using the various REQUIRE
options, see the description of REQUIRE
in Section 13.7.1.2, “CREATE USER Syntax”.
The path to a file in PEM format that contains a list of
trusted SSL certificate authorities. This option implies
--ssl
when used on the
server side, and on the client side before MySQL 5.7.3.
If you use encryption when establishing a client connection,
to tell the client not to authenticate the server
certificate, specify neither
--ssl-ca
nor
--ssl-capath
. The server
still verifies the client according to any applicable
requirements established for the client account, and it
still uses any --ssl-ca
or
--ssl-capath
option values
specified at server startup.
The path to a directory that contains trusted SSL
certificate authority certificates in PEM format. This
option implies --ssl
when
used on the server side, and on the client side before MySQL
5.7.3.
If you use encryption when establishing a client connection,
to tell the client not to authenticate the server
certificate, specify neither
--ssl-ca
nor
--ssl-capath
. The server
still verifies the client according to any applicable
requirements established for the client account, and it
still uses any --ssl-ca
or
--ssl-capath
option values
specified at server startup.
MySQL distributions compiled using OpenSSL support the
--ssl-capath
option (see
Section 6.3.11.1, “OpenSSL Versus yaSSL”). Distributions
compiled using yaSSL do not because yaSSL does not look in
any directory and does not follow a chained certificate
tree. yaSSL requires that all components of the CA
certificate tree be contained within a single CA certificate
tree and that each certificate in the file has a unique
SubjectName value. To work around this yaSSL limitation,
concatenate the individual certificate files comprising the
certificate tree into a new file and specify that file as
the value of the --ssl-ca
option.
The name of the SSL certificate file in PEM format to use
for establishing a secure connection. This option implies
--ssl
when used on the
server side, and on the client side before MySQL 5.7.3.
A list of permissible ciphers to use for connection
encryption. If no cipher in the list is supported, encrypted
connections will not work. This option implies
--ssl
when used on the
server side, and on the client side before MySQL 5.7.3.
For greatest portability,
cipher_list
should be a list of
one or more cipher names, separated by colons. This format
is understood both by OpenSSL and yaSSL. Examples:
--ssl-cipher=AES128-SHA --ssl-cipher=DHE-RSA-AES256-SHA:AES128-SHA
OpenSSL supports a more flexible syntax for specifying ciphers, as described in the OpenSSL documentation at http://www.openssl.org/docs/apps/ciphers.html. However, yaSSL does not, so attempts to use that extended syntax fail for a MySQL distribution compiled using yaSSL.
For information about which encryption ciphers MySQL supports, see Section 6.3.11.3, “Secure Connection Protocols and Ciphers”.
The path to a file containing certificate revocation lists
in PEM format. This option implies
--ssl
when used on the
server side, and on the client side before MySQL 5.7.3.
If neither --ssl-crl
nor
--ssl-crlpath
is given, no
CRL checks are performed, even if the CA path contains
certificate revocation lists.
MySQL distributions compiled using OpenSSL support the
--ssl-crl
option (see
Section 6.3.11.1, “OpenSSL Versus yaSSL”). Distributions
compiled using yaSSL do not because revocation lists do not
work with yaSSL.
The path to a directory that contains files containing
certificate revocation lists in PEM format. This option
implies --ssl
when used on
the server side, and on the client side before MySQL 5.7.3.
If neither --ssl-crl
nor
--ssl-crlpath
is given, no
CRL checks are performed, even if the CA path contains
certificate revocation lists.
MySQL distributions compiled using OpenSSL support the
--ssl-crlpath
option (see
Section 6.3.11.1, “OpenSSL Versus yaSSL”). Distributions
compiled using yaSSL do not because revocation lists do not
work with yaSSL.
The name of the SSL key file in PEM format to use for
establishing a secure connection. This option implies
--ssl
when used on the
server side, and on the client side before MySQL 5.7.3.
If the key file is protected by a passphrase, the program prompts the user for the passphrase. The password must be given interactively; it cannot be stored in a file. If the passphrase is incorrect, the program continues as if it could not read the key.
For better security, use a certificate with an RSA key size of of 2048 bits or more.
This option is available only for client programs, not the server. It specifies the security state of the connection to the server. The following option values are permitted:
PREFERRED
: Establish a secure
(encrypted) connection if the server supports secure
connections. Fall back to an unencrypted connection
otherwise. This is the default if
--ssl-mode
is not
specified.
DISABLED
: Establish an unencrypted
connection. This is like the legacy
--ssl=0
option or its
synonyms
(--skip-ssl
,
--disable-ssl
).
REQUIRED
: Establish a secure
connection if the server supports secure connections.
The connection attempt fails if a secure connection
cannot be established.
VERIFY_CA
: Like
REQUIRED
, but additionally verify the
server TLS certificate against the configured
Certificate Authority (CA) certificates. The connection
attempt fails if no valid matching CA certificates are
found.
VERIFY_IDENTITY
: Like
VERIFY_CA
, but additionally verify
that the server certificate matches the host to which
the connection is attempted. This is like the legacy
--ssl-verify-server-cert
option.
Use of the --ssl-ca
or
--ssl-capath
option implies
--ssl-mode=VERIFY_CA
, if
--ssl-mode
is not explicitly
set otherwise.
If --ssl-mode
is explicit,
use of a value other than VERIFY_CA
or
VERIFY_IDENTITY
with an explicit
--ssl-ca
or
--ssl-capath
option produces
a warning that no verification of the server certificate
will be done, despite CA certificate options being
specified.
The --ssl-mode
option was
added in MySQL 5.7.11.
This option is deprecated as of MySQL 5.7.11 and will be
removed in a future MySQL release. It is preferable to use
--ssl-mode=VERIFY_IDENTITY
.
This option is available only for client programs, not the server. It causes the client to check the server's Common Name value in the certificate that the server sends to the client. The client verifies that name against the host name the client uses for connecting to the server, and the connection fails if there is a mismatch. For encrypted connections, this option helps prevent man-in-the-middle attacks. Verification is disabled by default.
For client programs, the protocols permitted by the client for encrypted connections. The value is a comma-separated list containing one or more protocol names. The protocols that can be named for this option depend on the SSL library used to compile MySQL. For details, see Section 6.3.11.3, “Secure Connection Protocols and Ciphers”.
This option was added in MySQL 5.7.10.
On the server side, the
tls_version
system variable
can be used instead.
The following discussion describes how to create the files required for SSL and RSA support in MySQL. File creation can be performed using facilities provided by MySQL itself, or by invoking the openssl command directly.
SSL certificate and key files enable MySQL to support secure connections using SSL. See Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
RSA key files enable MySQL to support secure password exchange
over unencrypted connections for accounts authenticated by the
sha256_password
plugin. See
Section 6.4.1.4, “The SHA-256 Authentication Plugin”.
MySQL provides two ways to create the SSL certificate and key files and RSA key-pair files required to support secure connections using SSL and secure password exchange using RSA over unencrypted connections, if those files are missing:
The server can autogenerate these files at startup.
Users can invoke the mysql_ssl_rsa_setup utility manually.
Server autogeneration and mysql_ssl_rsa_setup help lower the barrier to using SSL by making it easier to generate the required files. However, certificates generated by these methods are self-signed, which is not very secure. After you gain experience using such files, consider obtaining a CA certificate from a registered certificate authority.
As of MySQL 5.7.5, MySQL servers have the capability of
automatically generating missing SSL and RSA files at startup,
for MySQL distributions compiled using OpenSSL. The
auto_generate_certs
and
sha256_password_auto_generate_rsa_keys
system variables control automatic generation of these files.
Both variables are enabled by default. They can be enabled at
startup and inspected but not set at runtime.
At startup, the server automatically generates server-side and
client-side SSL certificate and key files in the data directory
if the auto_generate_certs
system variable is enabled, no SSL options other than
--ssl
are specified, and the
server-side SSL files are missing from the data directory. These
files enable secure client connections using SSL; see
Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
The server checks the data directory for SSL files with the following names:
ca.pem server-cert.pem server-key.pem
If any of those files are present, the server creates no SSL files. Otherwise, it creates them, plus some additional files:
ca.pem Self-signed CA certificate ca-key.pem CA private key server-cert.pem Server certificate server-key.pem Server private key client-cert.pem Client certificate client-key.pem Client private key
If the server autogenerates SSL files, it uses the names of
the ca.pem
,
server-cert.pem
, and
server-key.pem
files to set the
corresponding system variables
(ssl_ca
,
ssl_cert
,
ssl_key
).
At startup, the server automatically generates RSA
private/public key-pair files in the data directory if the
sha256_password_auto_generate_rsa_keys
system variable is enabled, no RSA options are specified, and
the RSA files are missing from the data directory. These files
enable secure password exchange using RSA over unencrypted
connections for accounts authenticated by the
sha256_password
plugin; see
Section 6.4.1.4, “The SHA-256 Authentication Plugin”.
The server checks the data directory for RSA files with the following names:
private_key.pem Private member of private/public key pair public_key.pem Public member of private/public key pair
If any of these files are present, the server creates no RSA files. Otherwise, it creates them.
If the server autogenerates the RSA files, it uses their
names to set the corresponding system variables
(sha256_password_private_key_path
,
sha256_password_public_key_path
).
As of MySQL 5.7.6, MySQL distributions include a mysql_ssl_rsa_setup utility that can be invoked manually to generate SSL and RSA files. This utility is included with all MySQL distributions (whether compiled using OpenSSL or yaSSL), but it does require that the openssl command be available. For usage instructions, see Section 4.4.5, “mysql_ssl_rsa_setup — Create SSL/RSA Files”.
SSL and RSA files created automatically by the server or by invoking mysql_ssl_rsa_setup have these characteristics:
SSL and RSA keys are 2048 bit.
The SSL CA certificate is self signed.
The SSL server and client certificates are signed with the
CA certificate and key, using the
sha256WithRSAEncryption
signature
algorithm.
SSL certificates use these Common Name (CN) values, with the appropriate certificate type (CA, Server, Client):
ca.pem: MySQL_Server_suffix
_Auto_Generated_CA_Certificate server-cert.pm: MySQL_Server_suffix
_Auto_Generated_Server_Certificate client-cert.pm: MySQL_Server_suffix
_Auto_Generated_Client_Certificate
The suffix
value is based on the
MySQL version number. For files generated by
mysql_ssl_rsa_setup, the suffix can be
specified explicitly using the
--suffix
option.
For files generated by the server, if the resulting CN
values exceed 64 characters, the
_
portion of the name is omitted.
suffix
SSL files have blank values for Country (C), State or Province (ST), Organization (O), Organization Unit Name (OU) and email address.
SSL files created by the server or by mysql_ssl_rsa_setup are valid for ten years from the time of generation. (Before MySQL 5.7.6, files created by the server are valid for one year.)
RSA files do not expire.
SSL files have different serial numbers for each certificate/key pair (1 for CA, 2 for Server, 3 for Client).
Files created automatically by the server are owned by the
account that runs the server. Files created using
mysql_ssl_rsa_setup are owned by the user
who invoked that program. This can be changed on systems
that support the chown()
system call if
the program is invoked by root
and the
--uid
option is
given to specify the user who should own the files.
On Unix and Unix-like systems, the file access mode is 644 for certificate files (that is, world readable) and 600 for key files (that is, accessible only by the account that runs the server).
To see the contents of an SSL certificate (for example, to check the range of dates over which it is valid), invoke openssl directly:
shell>openssl x509 -text -in ca.pem
shell>openssl x509 -text -in server-cert.pem
shell>openssl x509 -text -in client-cert.pem
It is also possible to check SSL certificate expiration information using this SQL statement:
mysql> SHOW STATUS LIKE 'Ssl_server_not%';
+-----------------------+--------------------------+
| Variable_name | Value |
+-----------------------+--------------------------+
| Ssl_server_not_after | Apr 28 14:16:39 2025 GMT |
| Ssl_server_not_before | May 1 14:16:39 2015 GMT |
+-----------------------+--------------------------+
This section describes how to use the openssl command to set up SSL certificate and key files for use by MySQL servers and clients. The first example shows a simplified procedure such as you might use from the command line. The second shows a script that contains more detail. The first two examples are intended for use on Unix and both use the openssl command that is part of OpenSSL. The third example describes how to set up SSL files on Windows.
There are easier alternatives to generating the files required for SSL than the procedure described here: Let the server autogenerate them or use the mysql_ssl_rsa_setup program. See Section 6.3.12.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
Whatever method you use to generate the certificate and key files, the Common Name value used for the server and client certificates/keys must each differ from the Common Name value used for the CA certificate. Otherwise, the certificate and key files will not work for servers compiled using OpenSSL. A typical error in this case is:
ERROR 2026 (HY000): SSL connection error: error:00000001:lib(0):func(0):reason(1)
The following example shows a set of commands to create MySQL server and client certificate and key files. You will need to respond to several prompts by the openssl commands. To generate test files, you can press Enter to all prompts. To generate files for production use, you should provide nonempty responses.
# Create clean environment shell>rm -rf newcerts
shell>mkdir newcerts && cd newcerts
# Create CA certificate shell>openssl genrsa 2048 > ca-key.pem
shell>openssl req -new -x509 -nodes -days 3600 \
-key ca-key.pem -out ca.pem
# Create server certificate, remove passphrase, and sign it # server-cert.pem = public key, server-key.pem = private key shell>openssl req -newkey rsa:2048 -days 3600 \
-nodes -keyout server-key.pem -out server-req.pem
shell>openssl rsa -in server-key.pem -out server-key.pem
shell>openssl x509 -req -in server-req.pem -days 3600 \
-CA ca.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem
# Create client certificate, remove passphrase, and sign it # client-cert.pem = public key, client-key.pem = private key shell>openssl req -newkey rsa:2048 -days 3600 \
-nodes -keyout client-key.pem -out client-req.pem
shell>openssl rsa -in client-key.pem -out client-key.pem
shell>openssl x509 -req -in client-req.pem -days 3600 \
-CA ca.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem
After generating the certificates, verify them:
shell> openssl verify -CAfile ca.pem server-cert.pem client-cert.pem
server-cert.pem: OK
client-cert.pem: OK
To see the contents of a certificate (for example, to check the range of dates over which a certificate is valid), invoke openssl like this:
shell>openssl x509 -text -in ca.pem
shell>openssl x509 -text -in server-cert.pem
shell>openssl x509 -text -in client-cert.pem
Now you have a set of files that can be used as follows:
ca.pem
: Use this as the argument to
--ssl-ca
on the server and
client sides. (The CA certificate, if used, must be the same
on both sides.)
server-cert.pem
,
server-key.pem
: Use these as the
arguments to --ssl-cert
and
--ssl-key
on the server
side.
client-cert.pem
,
client-key.pem
: Use these as the
arguments to --ssl-cert
and
--ssl-key
on the client
side.
To use the files for SSL connections, see Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
Here is an example script that shows how to set up SSL certificate and key files for MySQL. After executing the script, use the files for SSL connections as described in Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
DIR=`pwd`/openssl PRIV=$DIR/private mkdir $DIR $PRIV $DIR/newcerts cp /usr/share/ssl/openssl.cnf $DIR replace ./demoCA $DIR -- $DIR/openssl.cnf # Create necessary files: $database, $serial and $new_certs_dir # directory (optional) touch $DIR/index.txt echo "01" > $DIR/serial # # Generation of Certificate Authority(CA) # openssl req -new -x509 -keyout $PRIV/cakey.pem -out $DIR/ca.pem \ -days 3600 -config $DIR/openssl.cnf # Sample output: # Using configuration from /home/monty/openssl/openssl.cnf # Generating a 1024 bit RSA private key # ................++++++ # .........++++++ # writing new private key to '/home/monty/openssl/private/cakey.pem' # Enter PEM pass phrase: # Verifying password - Enter PEM pass phrase: # ----- # You are about to be asked to enter information that will be # incorporated into your certificate request. # What you are about to enter is what is called a Distinguished Name # or a DN. # There are quite a few fields but you can leave some blank # For some fields there will be a default value, # If you enter '.', the field will be left blank. # ----- # Country Name (2 letter code) [AU]:FI # State or Province Name (full name) [Some-State]:. # Locality Name (eg, city) []: # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB # Organizational Unit Name (eg, section) []: # Common Name (eg, YOUR name) []:MySQL admin # Email Address []: # # Create server request and key # openssl req -new -keyout $DIR/server-key.pem -out \ $DIR/server-req.pem -days 3600 -config $DIR/openssl.cnf # Sample output: # Using configuration from /home/monty/openssl/openssl.cnf # Generating a 1024 bit RSA private key # ..++++++ # ..........++++++ # writing new private key to '/home/monty/openssl/server-key.pem' # Enter PEM pass phrase: # Verifying password - Enter PEM pass phrase: # ----- # You are about to be asked to enter information that will be # incorporated into your certificate request. # What you are about to enter is what is called a Distinguished Name # or a DN. # There are quite a few fields but you can leave some blank # For some fields there will be a default value, # If you enter '.', the field will be left blank. # ----- # Country Name (2 letter code) [AU]:FI # State or Province Name (full name) [Some-State]:. # Locality Name (eg, city) []: # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB # Organizational Unit Name (eg, section) []: # Common Name (eg, YOUR name) []:MySQL server # Email Address []: # # Please enter the following 'extra' attributes # to be sent with your certificate request # A challenge password []: # An optional company name []: # # Remove the passphrase from the key # openssl rsa -in $DIR/server-key.pem -out $DIR/server-key.pem # # Sign server cert # openssl ca -cert $DIR/ca.pem -policy policy_anything \ -out $DIR/server-cert.pem -config $DIR/openssl.cnf \ -infiles $DIR/server-req.pem # Sample output: # Using configuration from /home/monty/openssl/openssl.cnf # Enter PEM pass phrase: # Check that the request matches the signature # Signature ok # The Subjects Distinguished Name is as follows # countryName :PRINTABLE:'FI' # organizationName :PRINTABLE:'MySQL AB' # commonName :PRINTABLE:'MySQL admin' # Certificate is to be certified until Sep 13 14:22:46 2003 GMT # (365 days) # Sign the certificate? [y/n]:y # # # 1 out of 1 certificate requests certified, commit? [y/n]y # Write out database with 1 new entries # Data Base Updated # # Create client request and key # openssl req -new -keyout $DIR/client-key.pem -out \ $DIR/client-req.pem -days 3600 -config $DIR/openssl.cnf # Sample output: # Using configuration from /home/monty/openssl/openssl.cnf # Generating a 1024 bit RSA private key # .....................................++++++ # .............................................++++++ # writing new private key to '/home/monty/openssl/client-key.pem' # Enter PEM pass phrase: # Verifying password - Enter PEM pass phrase: # ----- # You are about to be asked to enter information that will be # incorporated into your certificate request. # What you are about to enter is what is called a Distinguished Name # or a DN. # There are quite a few fields but you can leave some blank # For some fields there will be a default value, # If you enter '.', the field will be left blank. # ----- # Country Name (2 letter code) [AU]:FI # State or Province Name (full name) [Some-State]:. # Locality Name (eg, city) []: # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB # Organizational Unit Name (eg, section) []: # Common Name (eg, YOUR name) []:MySQL user # Email Address []: # # Please enter the following 'extra' attributes # to be sent with your certificate request # A challenge password []: # An optional company name []: # # Remove the passphrase from the key # openssl rsa -in $DIR/client-key.pem -out $DIR/client-key.pem # # Sign client cert # openssl ca -cert $DIR/ca.pem -policy policy_anything \ -out $DIR/client-cert.pem -config $DIR/openssl.cnf \ -infiles $DIR/client-req.pem # Sample output: # Using configuration from /home/monty/openssl/openssl.cnf # Enter PEM pass phrase: # Check that the request matches the signature # Signature ok # The Subjects Distinguished Name is as follows # countryName :PRINTABLE:'FI' # organizationName :PRINTABLE:'MySQL AB' # commonName :PRINTABLE:'MySQL user' # Certificate is to be certified until Sep 13 16:45:17 2003 GMT # (365 days) # Sign the certificate? [y/n]:y # # # 1 out of 1 certificate requests certified, commit? [y/n]y # Write out database with 1 new entries # Data Base Updated # # Create a my.cnf file that you can use to test the certificates # cat <<EOF > $DIR/my.cnf [client] ssl-ca=$DIR/ca.pem ssl-cert=$DIR/client-cert.pem ssl-key=$DIR/client-key.pem [mysqld] ssl-ca=$DIR/ca.pem ssl-cert=$DIR/server-cert.pem ssl-key=$DIR/server-key.pem EOF
Download OpenSSL for Windows if it is not installed on your system. An overview of available packages can be seen here:
http://www.slproweb.com/products/Win32OpenSSL.html
Choose the Win32 OpenSSL Light or Win64 OpenSSL Light package,
depending on your architecture (32-bit or 64-bit). The default
installation location will be
C:\OpenSSL-Win32
or
C:\OpenSSL-Win64
, depending on which package
you downloaded. The following instructions assume a default
location of C:\OpenSSL-Win32
. Modify this as
necessary if you are using the 64-bit package.
If a message occurs during setup indicating
'...critical component is missing: Microsoft Visual C++
2008 Redistributables'
, cancel the setup and download
one of the following packages as well, again depending on your
architecture (32-bit or 64-bit):
Visual C++ 2008 Redistributables (x86), available at:
http://www.microsoft.com/downloads/details.aspx?familyid=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF
Visual C++ 2008 Redistributables (x64), available at:
http://www.microsoft.com/downloads/details.aspx?familyid=bd2a6171-e2d6-4230-b809-9a8d7548c1b6
After installing the additional package, restart the OpenSSL setup procedure.
During installation, leave the default
C:\OpenSSL-Win32
as the install path, and
also leave the default option 'Copy OpenSSL DLL files
to the Windows system directory'
selected.
When the installation has finished, add
C:\OpenSSL-Win32\bin
to the Windows System
Path variable of your server:
On the Windows desktop, right-click the My Computer icon, and select .
Select the
tab from the menu that appears, and click the button.Under System Variables, select , then click the button. The dialogue should appear.
Add ';C:\OpenSSL-Win32\bin'
to the end
(notice the semicolon).
Press OK 3 times.
Check that OpenSSL was correctly integrated into the Path variable by opening a new command console (Start>Run>cmd.exe) and verifying that OpenSSL is available:
Microsoft Windows [Version ...] Copyright (c) 2006 Microsoft Corporation. All rights reserved. C:\Windows\system32>cd \
C:\>openssl
OpenSSL>exit
<<< If you see the OpenSSL prompt, installation was successful. C:\>
Depending on your version of Windows, the preceding path-setting instructions might differ slightly.
After OpenSSL has been installed, use instructions similar to those from Example 1 (shown earlier in this section), with the following changes:
Change the following Unix commands:
# Create clean environment shell>rm -rf newcerts
shell>mkdir newcerts && cd newcerts
On Windows, use these commands instead:
# Create clean environment shell>md c:\newcerts
shell>cd c:\newcerts
When a '\'
character is shown at the end
of a command line, this '\'
character
must be removed and the command lines entered all on a
single line.
After generating the certificate and key files, to use them for SSL connections, see Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
This section describes how to use the openssl
command to set up the RSA key files that enable MySQL to support
secure password exchange over unencrypted connections for
accounts authenticated by the sha256_password
plugin.
There are easier alternatives to generating the files required for RSA than the procedure described here: Let the server autogenerate them or use the mysql_ssl_rsa_setup program. See Section 6.3.12.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
To create the RSA private and public key-pair files, run these commands while logged into the system account used to run the MySQL server so the files will be owned by that account:
openssl genrsa -out private_key.pem 2048 openssl rsa -in private_key.pem -pubout -out public_key.pem
Those commands create 2,048-bit keys. To create stronger keys, use a larger value.
Then set the access modes for the key files. The private key should be readable only by the server, whereas the public key can be freely distributed to client users:
chmod 400 private_key.pem chmod 444 public_key.pem
This section describes how to get a secure connection to a remote
MySQL server with SSH. The information was provided by David
Carlson <dcarlson@mplcomm.com>
.
Install an SSH client on your Windows machine. For a comparison of SSH clients, see http://en.wikipedia.org/wiki/Comparison_of_SSH_clients.
Start your Windows SSH client. Set Host_Name =
.
Set
yourmysqlserver_URL_or_IP
userid=
to log in to your server. This your_userid
userid
value
might not be the same as the user name of your MySQL account.
Set up port forwarding. Either do a remote forward (Set
local_port: 3306
, remote_host:
,
yourmysqlservername_or_ip
remote_port: 3306
) or a local forward (Set
port: 3306
, host:
localhost
, remote port: 3306
).
Save everything, otherwise you will have to redo it the next time.
Log in to your server with the SSH session you just created.
On your Windows machine, start some ODBC application (such as Access).
Create a new file in Windows and link to MySQL using the ODBC
driver the same way you normally do, except type in
localhost
for the MySQL host server, not
yourmysqlservername
.
At this point, you should have an ODBC connection to MySQL, encrypted using SSH.
Applications can use the following guidelines to perform SQL-based auditing that ties database activity to MySQL accounts.
MySQL accounts correspond to rows in the
mysql.user
table. When a client connects
successfully, the server authenticates the client to a particular
row in this table. The User
and
Host
column values in this row uniquely
identify the account and correspond to the
'
format in which account names are written in SQL statements.
user_name
'@'host_name
'
The account used to authenticate a client determines which
privileges the client has. Normally, the
CURRENT_USER()
function can be
invoked to determine which account this is for the client user.
Its value is constructed from the User
and
Host
columns of the user
table row for the account.
However, there are circumstances under which the
CURRENT_USER()
value corresponds
not to the client user but to a different account. This occurs in
contexts when privilege checking is not based the client's
account:
Stored routines (procedures and functions) defined with the
SQL SECURITY DEFINER
characteristic
Views defined with the SQL SECURITY DEFINER
characteristic
Triggers and events
In those contexts, privilege checking is done against the
DEFINER
account and
CURRENT_USER()
refers to that
account, not to the account for the client who invoked the stored
routine or view or who caused the trigger to activate. To
determine the invoking user, you can call the
USER()
function, which returns a
value indicating the actual user name provided by the client and
the host from which the client connected. However, this value does
not necessarily correspond directly to an account in the
user
table, because the
USER()
value never contains
wildcards, whereas account values (as returned by
CURRENT_USER()
) may contain user
name and host name wildcards.
For example, a blank user name matches any user, so an account of
''@'localhost'
enables clients to connect as an
anonymous user from the local host with any user name. In this
case, if a client connects as user1
from the
local host, USER()
and
CURRENT_USER()
return different
values:
mysql> SELECT USER(), CURRENT_USER();
+-----------------+----------------+
| USER() | CURRENT_USER() |
+-----------------+----------------+
| user1@localhost | @localhost |
+-----------------+----------------+
The host name part of an account can contain wildcards, too. If
the host name contains a '%'
or
'_'
pattern character or uses netmask notation,
the account can be used for clients connecting from multiple hosts
and the CURRENT_USER()
value will
not indicate which one. For example, the account
'user2'@'%.example.com'
can be used by
user2
to connect from any host in the
example.com
domain. If user2
connects from remote.example.com
,
USER()
and
CURRENT_USER()
return different
values:
mysql> SELECT USER(), CURRENT_USER();
+--------------------------+---------------------+
| USER() | CURRENT_USER() |
+--------------------------+---------------------+
| user2@remote.example.com | user2@%.example.com |
+--------------------------+---------------------+
If an application must invoke
USER()
for user auditing (for
example, if it does auditing from within triggers) but must also
be able to associate the USER()
value with an account in the user
table, it is
necessary to avoid accounts that contain wildcards in the
User
or Host
column.
Specifically, do not permit User
to be empty
(which creates an anonymous-user account), and do not permit
pattern characters or netmask notation in Host
values. All accounts must have a nonempty User
value and literal Host
value.
With respect to the previous examples, the
''@'localhost'
and
'user2'@'%.example.com'
accounts should be
changed not to use wildcards:
RENAME USER ''@'localhost' TO 'user1'@'localhost'; RENAME USER 'user2'@'%.example.com' TO 'user2'@'remote.example.com';
If user2
must be able to connect from several
hosts in the example.com
domain, there should
be a separate account for each host.
To extract the user name or host name part from a
CURRENT_USER()
or
USER()
value, use the
SUBSTRING_INDEX()
function:
mysql>SELECT SUBSTRING_INDEX(CURRENT_USER(),'@',1);
+---------------------------------------+ | SUBSTRING_INDEX(CURRENT_USER(),'@',1) | +---------------------------------------+ | user1 | +---------------------------------------+ mysql>SELECT SUBSTRING_INDEX(CURRENT_USER(),'@',-1);
+----------------------------------------+ | SUBSTRING_INDEX(CURRENT_USER(),'@',-1) | +----------------------------------------+ | localhost | +----------------------------------------+
MySQL includes several plugins that implement security features:
Plugins for authenticating attempts by clients to connect to MySQL Server. Plugins are available for several authentication protocols. For general discussion of the authentication process, see Section 6.3.8, “Pluggable Authentication”. For characteristics of specific authentication plugins, see Section 6.4.1, “Authentication Plugins”.
A password-validation plugin for implementing password strength policies and assessing the strength of potential passwords. See Section 6.4.2, “The Password Validation Plugin”.
A keyring plugin that provides secure storage for sensitive information. See Section 6.4.3, “The MySQL Keyring”.
(MySQL Enterprise Edition only) MySQL Enterprise Audit, implemented using a server plugin, uses the open MySQL Audit API to enable standard, policy-based monitoring and logging of connection and query activity executed on specific MySQL servers. Designed to meet the Oracle audit specification, MySQL Enterprise Audit provides an out of box, easy to use auditing and compliance solution for applications that are governed by both internal and external regulatory guidelines.
(MySQL Enterprise Edition only) MySQL Enterprise Firewall, an application-level firewall that enables database administrators to permit or deny SQL statement execution based on matching against whitelists of accepted statement patterns. This helps harden MySQL Server against attacks such as SQL injection or attempts to exploit applications by using them outside of their legitimate query workload characteristics.
The following sections describe the authentication plugins available in MySQL.
The default plugin is mysql_native_password
unless the
default_authentication_plugin
system variable is set otherwise.
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 6.4.1.2, “The Old Native Authentication Plugin”.
For information about these password hashing methods, see
Section 6.1.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.
Table 6.9 MySQL Native Password Authentication Plugin
Server-side plugin name | mysql_native_password |
Client-side plugin name | mysql_native_password |
Library object file name | None (plugins are built in) |
The plugin exists in both client and server form:
The server-side plugin is built into the server, need not be loaded explicitly, and cannot be disabled by unloading it.
The client-side plugin is built into the
libmysqlclient
client library as of MySQL
5.5.7 and available to any program linked against
libmysqlclient
from that version or
newer.
MySQL client programs use
mysql_native_password
by default. The
--default-auth
option can be
used as a hint about which client-side plugin the program
can expect to use:
shell> mysql --default-auth=mysql_native_password ...
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. As of
MySQL 5.7.2, the server requires the plugin value to be
nonempty, and as of 5.7.5, support for
mysql_old_password
is removed.
For general information about pluggable authentication in MySQL, see Section 6.3.8, “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 6.4.1.1, “The Native Authentication Plugin”. For information
about these password hashing methods, see
Section 6.1.2.4, “Password Hashing in MySQL”.
Passwords that use the pre-4.1 hashing method are less secure
than passwords that use the native password hashing method and
should be avoided. Pre-4.1 passwords are deprecated and
support for them (including the
mysql_old_password
plugin) is removed in
MySQL 5.7.5. For account upgrade instructions, see
Section 6.4.1.3, “Migrating Away from Pre-4.1 Password Hashing and the mysql_old_password
Plugin”.
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.
Table 6.10 MySQL Old Native Authentication Plugin
Server-side plugin name | mysql_old_password |
Client-side plugin name | mysql_old_password |
Library object file name | None (plugins are built in) |
The plugin exists in both client and server form:
The server-side plugin is built into the server, need not be loaded explicitly, and cannot be disabled by unloading it.
The client-side plugin is built into the
libmysqlclient
client library as of MySQL
5.5.7 and available to any program linked against
libmysqlclient
from that version or
newer.
MySQL client programs can use the
--default-auth
option to
specify the mysql_old_password
plugin as
a hint about which client-side plugin the program can expect
to use:
shell> mysql --default-auth=mysql_old_password ...
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. As of
MySQL 5.7.2, the server requires the plugin value to be
nonempty, and as of 5.7.5, support for
mysql_old_password
is removed.
For general information about pluggable authentication in MySQL, see Section 6.3.8, “Pluggable Authentication”. For information about setting up proxy users, see Section 6.3.9, “Proxy Users”.
The MySQL server authenticates connection attempts for each
account listed in the mysql.user
table using
the authentication plugin named in the plugin
column. If the plugin
column is empty, the
server authenticates the account as follows:
Before MySQL 5.7.2, the server uses the
mysql_native_password
or
mysql_old_password
plugin implicitly,
depending on the format of the password hash in the
Password
column. If the
Password
value is empty or a 4.1 password
hash (41 characters), the server uses
mysql_native_password
. If the password
value is a pre-4.1 password hash (16 characters), the server
uses mysql_old_password
. (For additional
information about these hash formats, see
Section 6.1.2.4, “Password Hashing in MySQL”.)
As of MySQL 5.7.2, the server requires the
plugin
column to be nonempty and disables
accounts that have an empty plugin
value.
Pre-4.1 password hashes and the
mysql_old_password
plugin are deprecated as
of MySQL 5.6.5 and support for them is removed in MySQL 5.7.5.
They provide a level of security inferior to that offered by 4.1
password hashing and the
mysql_native_password
plugin.
Given the requirement in MySQL 5.7.2 that the
plugin
column must be nonempty, coupled with
removal of mysql_old_password
support in
5.7.5, DBAs are advised to upgrade accounts as follows:
Upgrade accounts that use
mysql_native_password
implicitly to use
it explicitly
Upgrade accounts that use
mysql_old_password
(either implicitly or
explicitly) to use mysql_native_password
explicitly
The instructions in this section describe how to perform those
upgrades. The result is that no account has an empty
plugin
value and no account uses pre-4.1
password hashing or the mysql_old_password
plugin.
As a variant on these instructions, DBAs might offer users the
choice to upgrade to the sha256_password
plugin, which authenticates using SHA-256 password hashes. For
information about this plugin, see
Section 6.4.1.4, “The SHA-256 Authentication Plugin”.
The following table lists the types of
mysql.user
accounts considered in this
discussion.
plugin Column | Password Column | Authentication Result | Upgrade Action |
---|---|---|---|
Empty | Empty | Implicitly uses mysql_native_password | Assign plugin |
Empty | 4.1 hash | Implicitly uses mysql_native_password | Assign plugin |
Empty | Pre-4.1 hash | Implicitly uses mysql_old_password | Assign plugin, rehash password |
mysql_native_password | Empty | Explicitly uses mysql_native_password | None |
mysql_native_password | 4.1 hash | Explicitly uses mysql_native_password | None |
mysql_old_password | Empty | Explicitly uses mysql_old_password | Upgrade plugin |
mysql_old_password | Pre-4.1 hash | Explicitly uses mysql_old_password | Upgrade plugin, rehash password |
Accounts corresponding to lines for the
mysql_native_password
plugin require no
upgrade action (because no change of plugin or hash format is
required). For accounts corresponding to lines for which the
password is empty, consider asking the account owners to choose
a password (or require it by using ALTER
USER
to expire empty account passwords).
Accounts that have an empty plugin and a 4.1 password hash use
mysql_native_password
implicitly. To upgrade
these accounts to use mysql_native_password
explicitly, execute these statements:
UPDATE mysql.user SET plugin = 'mysql_native_password' WHERE plugin = '' AND (Password = '' OR LENGTH(Password) = 41); FLUSH PRIVILEGES;
Before MySQL 5.7.2, you can execute those statements to uprade accounts proactively. As of MySQL 5.7.2, you can run mysql_upgrade, which performs the same operation among its upgrade actions.
Notes:
The upgrade operation just described is safe to execute at
any time because it makes the
mysql_native_password
plugin explicit
only for accounts that already use it implicitly.
This operation requires no password changes, so it can be performed without affecting users or requiring their involvement in the upgrade process.
Accounts that use mysql_old_password
(either
implicitly or explicitly) should be upgraded to use
mysql_native_password
explicitly. This
requires changing the plugin and changing
the password from pre-4.1 to 4.1 hash format.
For the accounts covered in this step that must be upgraded, one of these conditions is true:
The account uses mysql_old_password
implicitly because the plugin
column is
empty and the password has the pre-4.1 hash format (16
characters).
The account uses mysql_old_password
explicitly.
To identify such accounts, use this query:
SELECT User, Host, Password FROM mysql.user WHERE (plugin = '' AND LENGTH(Password) = 16) OR plugin = 'mysql_old_password';
The following discussion provides two methods for updating that set of accounts. They have differing characteristics, so read both and decide which is most suitable for a given MySQL installation.
Method 1.
Characteristics of this method:
It requires that server and clients be run with
secure_auth=0
until all users have been
upgraded to mysql_native_password
.
(Otherwise, users cannot connect to the server using their
old-format password hashes for the purpose of upgrading to a
new-format hash.)
It works for MySQL 5.5 through 5.7.1. As of 5.7.2, it does not work because the server requires accounts to have a nonempty plugin and disables them otherwise. Therefore, if you have already upgraded to 5.7.2 or later, choose Method 2, described later.
You should ensure that the server is running with
secure_auth=0
.
For all accounts that use mysql_old_password
explicitly, set them to the empty plugin:
UPDATE mysql.user SET plugin = '' WHERE plugin = 'mysql_old_password'; FLUSH PRIVILEGES;
To also expire the password for affected accounts, use these statements instead:
UPDATE mysql.user SET plugin = '', password_expired = 'Y' WHERE plugin = 'mysql_old_password'; FLUSH PRIVILEGES;
Now affected users can reset their password to use 4.1 hashing. Ask each user who now has an empty plugin to connect to the server and execute these statements:
SET old_passwords = 0;
SET PASSWORD = PASSWORD('user-chosen-password
');
The client-side --secure-auth
option is enabled by default, so remind users to disable it or
they will be unable to connect:
shell> mysql -u user_name
-p --secure-auth=0
After an affected user has executed those statements, you can
set the corresponding account plugin to
mysql_native_password
to make the plugin
explicit. Or you can periodically run these statements to find
and fix any accounts for which affected users have reset their
password:
UPDATE mysql.user SET plugin = 'mysql_native_password' WHERE plugin = '' AND (Password = '' OR LENGTH(Password) = 41); FLUSH PRIVILEGES;
When there are no more accounts with an empty plugin, this query returns an empty result:
SELECT User, Host, Password FROM mysql.user WHERE (plugin = '' AND LENGTH(Password) = 16);
At that point, all accounts have been migrated away from pre-4.1
password hashing and the server no longer need be run with
secure_auth=0
.
Method 2.
Characteristics of this method:
It assigns each affected account a new password, so you must tell each such user the new password and ask the user to choose a new one. Communication of passwords to users is outside the scope of MySQL, but should be done carefully.
It does not require server or clients to be run with
secure_auth=0
.
It works for any version of MySQL 5.5 or later (and for 5.7.6 or later has an easier variant).
With this method, you update each account separately due to the need to set passwords individually. Choose a different password for each account.
Suppose that 'user1'@'localhost'
is one of
the accounts to be upgraded. Modify it as follows:
In MySQL 5.7.6 and higher, ALTER USER
provides the capability of modifying both the account
password and its authentication plugin, so you need not
modify the mysql.user
table directly:
ALTER USER 'user1'@'localhost'
IDENTIFIED WITH mysql_native_password BY 'DBA-chosen-password
';
To also expire the account password, use this statement instead:
ALTER USER 'user1'@'localhost'
IDENTIFIED WITH mysql_native_password BY 'DBA-chosen-password
'
PASSWORD EXPIRE;
Then tell the user the new password and ask the user to connect to the server with that password and execute this statement to choose a new password:
ALTER USER USER() IDENTIFIED BY 'user-chosen-password
';
Before MySQL 5.7.6, you must modify the
mysql.user
table directly using these
statements:
SET old_passwords = 0;
UPDATE mysql.user SET plugin = 'mysql_native_password',
Password = PASSWORD('DBA-chosen-password
')
WHERE (User, Host) = ('user1', 'localhost');
FLUSH PRIVILEGES;
To also expire the account password, use these statements instead:
SET old_passwords = 0;
UPDATE mysql.user SET plugin = 'mysql_native_password',
Password = PASSWORD('DBA-chosen-password
'), password_expired = 'Y'
WHERE (User, Host) = ('user1', 'localhost');
FLUSH PRIVILEGES;
Then tell the user the new password and ask the user to connect to the server with that password and execute these statements to choose a new password:
SET old_passwords = 0;
SET PASSWORD = PASSWORD('user-chosen-password
');
Repeat for each account to be upgraded.
MySQL provides an authentication plugin that implements SHA-256 hashing for user account passwords.
To connect to the server using an account that authenticates
with the sha256_password
plugin, you must
use either an SSL connection or an unencrypted connection that
encrypts the password using RSA, as described later in this
section. Either way, use of the
sha256_password
plugin requires that MySQL
be built with SSL capabilities. See
Section 6.3.11, “Using Secure Connections”.
The following table shows the plugin names on the server and client sides.
Table 6.11 MySQL SHA-256 Authentication Plugin
Server-side plugin name | sha256_password |
Client-side plugin name | sha256_password |
Library object file name | None (plugins are built in) |
The server-side sha256_password
plugin is
built into the server, need not be loaded explicitly, and cannot
be disabled by unloading it. Similarly, clients need not specify
the location of the client-side plugin.
To set up an account that uses the
sha256_password
plugin for SHA-256 password
hashing, use the following statement for MySQL 5.7.6 and up:
CREATE USER 'sha256user'@'localhost' IDENTIFIED WITH sha256_password BY 'Sh@256Pa33';
Before MySQL 5.7.6, use this procedure:
Create the account and specify that it authenticates using
the sha256_password
plugin:
CREATE USER 'sha256user'@'localhost' IDENTIFIED WITH sha256_password;
Set the old_passwords
system variable to 2 to cause the
PASSWORD()
function to use
SHA-256 hashing of password strings, then set the account
password:
SET old_passwords = 2; SET PASSWORD FOR 'sha256user'@'localhost' = PASSWORD('Sh@256Pa33');
Alternatively, start the server with the default authentication
plugin set to sha256_password
. For example,
put these lines in the server option file:
[mysqld] default_authentication_plugin=sha256_password
That causes the sha256_password
plugin to be
used by default for new accounts. As a result, it is possible to
create the account and set its password without naming the
plugin explicitly using this CREATE
USER
syntax:
CREATE USER 'sha256user'@'localhost' IDENTIFIED BY 'Sh@256Pa33';
In this case, the server assigns the
sha256_password
plugin to the account and
encrypts the password using SHA-256.
Accounts in the mysql.user
table that use
SHA-256 passwords can be identified as rows with
'sha256_password'
in the
plugin
column and a SHA-256 password hash in
the authentication_string
column.
Another consequence of using sha256_password
as the default authentication plugin is that to create an
account that uses a different plugin, you must specify the
plugin using an IDENTIFIED WITH
clause in the
CREATE USER
statement. For
example, to use the mysql_native_password
plugin, use this statement for MySQL 5.7.6 and up:
CREATE USER 'nativeuser'@'localhost' IDENTIFIED WITH mysql_native_password BY 'N@tivePa33';
Before MySQL 5.7.6, create the account, then set
old_passwords
appropriately for
the plugin before using SET
PASSWORD
to set the account password.
CREATE USER 'nativeuser'@'localhost' IDENTIFIED WITH mysql_native_password; SET old_passwords = 0; SET PASSWORD FOR 'nativeuser'@'localhost' = PASSWORD('N@tivePa33');
Before MySQL 5.7.6, to set or change the password for an account
that authenticates using the sha256_password
plugin, be sure that the value of
old_passwords
is 2 before using
SET PASSWORD
. If
old_passwords
has a value other
than 2, an error occurs for attempts to set the password:
mysql>SET old_passwords = 0;
mysql>SET PASSWORD FOR 'sha256user'@'localhost' = PASSWORD('NewSh@256Pa33');
ERROR 1827 (HY000): The password hash doesn't have the expected format. Check if the correct password algorithm is being used with the PASSWORD() function.
For more information about
old_passwords
and
PASSWORD()
, see
Section 5.1.4, “Server System Variables”, and
Section 12.13, “Encryption and Compression Functions”.
MySQL can be compiled using either OpenSSL or yaSSL (see
Section 6.3.11.1, “OpenSSL Versus yaSSL”). The
sha256_password
plugin works with
distributions compiled using either package, but if MySQL is
compiled using OpenSSL, RSA encryption is available and
sha256_password
implements the following
additional capabilities. (To enable these capabilities, you must
also follow the RSA configuration procedure given later in this
section.)
It is possible for the client to transmit passwords to the server using RSA encryption during the client connection process, as described later.
The server exposes two additional system variables,
sha256_password_private_key_path
and
sha256_password_public_key_path
.
It is intended that the database administrator will set
these to the names of the RSA private and public key-pair
files at server startup if the key files have names that
differ from the system variable default values.
The server exposes a status variable,
Rsa_public_key
, that
displays the RSA public key value.
The mysql and
mysqltest client programs support a
--server-public-key-path
option for specifying an RSA public key file explicitly.
For clients that use the sha256_password
plugin, passwords are never exposed as cleartext when connecting
to the server. How password transmission occurs depends on
whether an SSL connection is used and whether RSA encryption is
available:
If an SSL connection is used, the password is sent as cleartext but cannot be snooped because the connection is encrypted using SSL.
If an SSL connection is not used but RSA encryption is available, the password is sent within an unencrypted connection, but the password is RSA-encrypted to prevent snooping. When the server receives the password, it decrypts it. A scramble is used in the encryption to prevent repeat attacks.
If an SSL connection is not used and RSA encryption is not
available, the sha256_password
plugin
causes the connection attempt to fail because the password
cannot be sent without being exposed as cleartext.
As mentioned previously, RSA password encryption is available only if MySQL was compiled using OpenSSL. The implication for MySQL distributions compiled using yaSSL is that SHA-256 passwords can be used only when clients use SSL to access the server. See Section 6.3.11.4, “Configuring MySQL to Use Secure Connections”.
Assuming that MySQL has been compiled using OpenSSL, the following procedure describes how to enable RSA encryption of passwords during the client connection process:
Create the RSA private and public key-pair files using the instructions in Section 6.3.12, “Creating SSL and RSA Certificates and Keys”.
If the private and public key files are located in the data
directory and are named private_key.pem
and public_key.pem
(the default values
of the
sha256_password_private_key_path
and
sha256_password_public_key_path
system variables), the server will use them automatically at
startup.
Otherwise, in the server option file, set the system variables to the key file names. If the files are located in the server data directory, you need not specify their full path names:
[mysqld] sha256_password_private_key_path=myprivkey.pem sha256_password_public_key_path=mypubkey.pem
If the key files are not located in the data directory, or to make their locations explicit in the system variable values, use full path names:
[mysqld] sha256_password_private_key_path=/usr/local/mysql/myprivkey.pem sha256_password_public_key_path=/usr/local/mysql/mypubkey.pem
Restart the server, then connect to it and check the
Rsa_public_key
status
variable value. The value will differ from that shown here,
but should be nonempty:
mysql> SHOW STATUS LIKE 'Rsa_public_key'\G
*************************** 1. row ***************************
Variable_name: Rsa_public_key
Value: -----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDO9nRUDd+KvSZgY7cNBZMNpwX6
MvE1PbJFXO7u18nJ9lwc99Du/E7lw6CVXw7VKrXPeHbVQUzGyUNkf45Nz/ckaaJa
aLgJOBCIDmNVnyU54OT/1lcs2xiyfaDMe8fCJ64ZwTnKbY2gkt1IMjUAB5Ogd5kJ
g8aV7EtKwyhHb0c30QIDAQAB
-----END PUBLIC KEY-----
If the value is empty, the server found some problem with the key files. Check the error log for diagnostic information.
After the server has been configured with the RSA key files,
clients have the option of using them to connect to the server
using accounts that authenticate with the
sha256_password
plugin. As mentioned
previously, such accounts can use either an SSL connection (in
which case RSA is not used) or an unencrypted connection that
encrypts the password using RSA. Assume for the following
discussion that SSL is not used. Connecting to the server
involves no special preparation on the client side. For example:
shell>mysql --ssl=0 -u sha256user -p
Enter password:Sh@256Pa33
For connection attempts by sha256user
, the
server determines that sha256_password
is the
appropriate authentication plugin and invokes it. The plugin
finds that the connection does not use SSL and thus requires the
password to be transmitted using RSA encryption. In this case,
the plugin sends the RSA public key to the client, which uses it
to encrypt the password and returns the result to the server.
The plugin uses the RSA key on the server side to decrypt the
password and accepts or rejects the connection based on whether
the password is correct.
The server sends the public key to the client as needed, but if a copy of the RSA public key is available on the client host, the client can use it to save a round trip in the client/server protocol:
shell> mysql --ssl=0 -u sha256user -p --server-public-key-path=file_name
The public key value in the file named by the
--server-public-key-path
option
should be the same as the key value in the server-side file
named by the
sha256_password_public_key_path
system variable. If the key file contains a valid public key
value but the value is incorrect, an access-denied error occurs.
If the key file does not contain a valid public key, the client
program cannot use it. In this case, the
sha256_password
plugin sends the public key
to the client as if no
--server-public-key-path
option
had been specified.
Client users can get the RSA public key two ways:
The database administrator can provide a copy of the public key file.
A client user who can connect to the server some other way
can use a SHOW STATUS LIKE
'Rsa_public_key'
statement and save the returned
key value in a file.
The PAM authentication plugin is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see http://www.mysql.com/products/.
As of MySQL 5.7.9, 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:
External authentication: The plugin enables MySQL Server to accept connections from users defined outside the MySQL grant tables and that authenticate using methods supported by PAM.
Proxy user support: The plugin can return to MySQL a user
name different from the login user, based on the groups the
external user is in and the authentication string provided.
This means that the plugin can return the MySQL user that
defines the privileges the external PAM-authenticated user
should have. For example, a PAM user named
joe
can connect and have the privileges
of the MySQL user named developer
.
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
or
user_name
''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 6.4.1.5.1, “Installing the PAM Authentication Plugin”.
Table 6.12 MySQL PAM Authentication Plugin
Server-side plugin name | authentication_pam |
Client-side plugin name | mysql_clear_password |
Library object file name | authentication_pam.so |
The library file includes only the server-side plugin. The
client-side plugin is built into the
libmysqlclient
client library. See
Section 6.4.1.8, “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 distribution to connect to a server that has the server-side plugin loaded.
For general information about pluggable authentication in MySQL, see Section 6.3.8, “Pluggable Authentication”. For proxy user information, see Section 6.3.9, “Proxy Users”.
The PAM authentication plugin 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 location of the plugin directory.
To enable the plugin, start the server with the
--plugin-load
option. For
example, put the following lines in your
my.cnf
file. If object files have a
suffix different from .so
on your system,
substitute the correct suffix.
[mysqld] plugin-load=authentication_pam.so
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement. See Section 5.1.8.2, “Obtaining Server Plugin Information”.
To associate a MySQL account with the PAM plugin, use the
plugin name authentication_pam
in the
IDENTIFIED WITH
clause of
CREATE USER
or
GRANT
statement that creates
the account.
This section describes how to use the PAM authentication plugin to connect from MySQL client programs to the server. It is assumed that the server-side plugin is enabled, as described previously.
The client-side plugin with which the PAM plugin communicates simply sends the password to the server in clear text so it can be passed to PAM. This may be a security problem in some configurations, but is necessary to use the server-side PAM library. To avoid problems if there is any possibility that the password would be intercepted, clients should connect to MySQL Server using a secure connection. See Section 6.4.1.8, “The Cleartext Client-Side Authentication Plugin”.
To refer to the PAM authentication plugin in the
IDENTIFIED WITH
clause of a
CREATE USER
or
GRANT
statement, use the name
authentication_pam
. For example:
CREATE USERuser
IDENTIFIED WITH authentication_pam AS 'authentication_string
';
The authentication string specifies the following types of information:
PAM supports the notion of “service name,” which is a name that the system administrator can use to configure the authentication method for a particular application. There can be several such “applications” associated with a single database server instance, so the choice of service name is left to the SQL application developer. When you define an account that should authenticate using PAM, specify the service name in the authentication string.
PAM provides a way for a PAM module to return to the server a MySQL user name other than the login name supplied at login time. Use the authentication string to control the mapping between login name and MySQL user name. If you want to take advantage of proxy user capabilities, the authentication string must include this kind of mapping.
For example, if the service name is mysql
and users in the root
and
users
PAM groups should be mapped to the
developer
and data_entry
MySQL users, respectively, use a statement like this:
CREATE USER user
IDENTIFIED WITH authentication_pam
AS 'mysql, root=developer, users=data_entry';
Authentication string syntax for the PAM authentication plugin follows these rules:
The string consists of a PAM service name, optionally followed by a group mapping list consisting of one or more keyword/value pairs each specifying a group name and a MySQL user name:
pam_service_name
[,group_name
=mysql_user_name
]...
The plugin parses the authentication string on each login check. To minimize overhead, keep the string as short as possible.
Each
pair must be preceded by a comma.
group_name
=mysql_user_name
Leading and trailing spaces not inside double quotation marks are ignored.
Unquoted pam_service_name
,
group_name
, and
mysql_user_name
values can
contain anything except equal sign, comma, or space.
If a pam_service_name
,
group_name
, or
mysql_user_name
value is quoted
with double quotation marks, everything between the
quotation marks is part of the value. This is necessary,
for example, if the value contains space characters. All
characters are legal except double quotation mark and
backslash (\
). To include either
character, escape it with a backslash.
If the plugin successfully authenticates a login name, it looks for a group mapping list in the authentication string and, if present, uses it to return a different user name to the MySQL server based on the groups the external user is a member of:
If the authentication string contains no group mapping list, the plugin returns the login name.
If the authentication string does contain a group mapping
list, the plugin examines each
pair in the list from left to right and tries to find a
match for the group_name
=mysql_user_name
group_name
value
in a non-MySQL directory of the groups assigned to the
authenticated user and returns
mysql_user_name
for the first
match it finds. If the plugin finds no match for any
group, it returns the login name. If the plugin is not
capable of looking up a group in a directory, it ignores
the group mapping list and returns the login name.
The following sections describe how to set up several authentication scenarios that use the PAM authentication plugin:
No proxy users. This uses PAM only to check login names
and passwords. Every external user permitted to connect to
MySQL Server should have a matching MySQL account that is
defined to use external PAM authentication. (For a MySQL
account of
to match the external user,
user_name
@host_name
user_name
must be the login
name and host_name
must match
the host from which the client connects.) Authentication
can be performed by various PAM-supported methods. The
discussion shows how to use traditional Unix passwords and
LDAP.
PAM authentication, when not done through proxy users or groups, requires the MySQL account to have the same user name as the Unix account. Because MySQL user names are limited to 32 characters (16 before MySQL 5.7.8; see Section 6.2.2, “Privilege System Grant Tables”), this limits PAM nonproxy authentication to Unix accounts with names of at most 16 characters.
Proxy login only and group mapping. For this scenario, create one or a few MySQL accounts that define different sets of privileges. (Ideally, nobody should connect using those accounts directly.) Then define a default user authenticating through PAM that uses some mapping scheme (usually by the external groups the users are in) to map all the external logins to the few MySQL accounts holding the privilege sets. Any user that logs in is mapped to one of the MySQL accounts and uses its privileges. The discussion shows how to set this up using Unix passwords, but other PAM methods such as LDAP could be used instead.
Variations on these scenarios are possible. For example, you can permit some users to log in directly (without proxying) but require others to connect through proxy users.
The examples make the following assumptions. You might need to make some adjustments if your system is set up differently.
The PAM configuration directory is
/etc/pam.d
.
The PAM service name is mysql
, which
means that you must set up a PAM file named
mysql
in the PAM configuration
directory (creating the file if it does not exist). If you
use a service name different from
mysql
, the file name will be different
and you must use a different name in the AS
'
clause
of auth_string
'CREATE USER
and
GRANT
statements.
The examples use a login name of
antonio
and password of
verysecret
. Change these to correspond
to the users you want to authenticate.
The PAM authentication plugin checks at initialization time
whether the AUTHENTICATION_PAM_LOG
environment value is set in the server's startup environment.
If so, the plugin enables logging of diagnostic messages to
the standard output. Depending on how your server is started,
the message might appear on the console or in the error log.
These messages can be helpful for debugging PAM-related
problems that occur when the plugin performs authentication.
For more information, see
Section 6.4.1.5.6, “PAM Authentication Plugin Debugging”.
This authentication scenario uses PAM only to check Unix user login names and passwords. Every external user permitted to connect to MySQL Server should have a matching MySQL account that is defined to use external PAM authentication.
Verify that Unix authentication in PAM permits you to log
in as antonio
with password
verysecret
.
Set up PAM to authenticate the mysql
service by creating a file named
/etc/pam.d/mysql
. The file contents
are system dependent, so check existing login-related
files in the /etc/pam.d
directory to
see what they look like. On Linux, the
mysql
file might look like this:
#%PAM-1.0 auth include password-auth account include password-auth
For Gentoo Linux, use system-login
rather than password-auth
. For OS X,
use login
rather than
password-auth
.
On Ubuntu and other Debian-based systems, use these file contents instead:
@include common-auth @include common-account @include common-session-noninteractive
Create a MySQL account with the same user name as the Unix login name and define it to authenticate using the PAM plugin:
CREATE USER 'antonio'@'localhost' IDENTIFIED WITH authentication_pam AS 'mysql'; GRANT ALL PRIVILEGES ON mydb.* TO 'antonio'@'localhost';
Connect to the MySQL server using the mysql command-line client. For example:
mysql --user=antonio --password=verysecret --enable-cleartext-plugin mydb
The server should permit the connection and the following query should return output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
+-------------------+-------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-------------------+-------------------+--------------+
| antonio@localhost | antonio@localhost | NULL |
+-------------------+-------------------+--------------+
This demonstrates that antonio
uses the
privileges granted to the antonio
MySQL
account, and that no proxying has occurred.
This authentication scenario uses PAM only to check LDAP user login names and passwords. Every external user permitted to connect to MySQL Server should have a matching MySQL account that is defined to use external PAM authentication.
Verify that LDAP authentication in PAM permits you to log
in as antonio
with password
verysecret
.
Set up PAM to authenticate the mysql
service through LDAP by creating a file named
/etc/pam.d/mysql
. The file contents
are system dependent, so check existing login-related
files in the /etc/pam.d
directory to
see what they look like. On Linux, the
mysql
file might look like this:
#%PAM-1.0 auth required pam_ldap.so account required pam_ldap.so
If PAM object files have a suffix different from
.so
on your system, substitute the
correct suffix.
The PAM file might have a different format on some systems.
MySQL account creation and connecting to the server is the same as previously described in Section 6.4.1.5.3, “Unix Password Authentication without Proxy Users”.
This authentication scheme uses proxying and group mapping to map users who connect to the MySQL server through PAM onto MySQL accounts that define different sets of privileges. Users do not connect directly through the accounts that define the privileges. Instead, they connect through a default proxy user authenticating through PAM that uses a mapping scheme to map all the external logins to the few MySQL accounts holding the privileges. Any user who connects is mapped to one of the MySQL accounts and uses its privileges.
The procedure shown here uses Unix password authentication. To use LDAP instead, see the early steps of Section 6.4.1.5.4, “LDAP Authentication without Proxy Users”.
Verify that Unix authentication in PAM permits you to log
in as antonio
with password
verysecret
and that
antonio
is a member of the
root
or users
group.
Set up PAM to authenticate the mysql
service. Put the following in
/etc/pam.d/mysql
:
#%PAM-1.0 auth include password-auth account include password-auth
use system-login
rather than
password-auth
. For OS X, use
login
rather than
password-auth
.
The PAM file might have a different format on some systems. For example, on Ubuntu and other Debian-based systems, use these file contents instead:
@include common-auth @include common-account @include common-session-noninteractive
Create a default proxy user (''@''
)
that maps the external PAM users to the proxied accounts.
It maps external users from the root
PAM group to the developer
MySQL
account and the external users from the
users
PAM group to the
data_entry
MySQL account:
CREATE USER ''@'' IDENTIFIED WITH authentication_pam AS 'mysql, root=developer, users=data_entry';
The mapping list following the service name is required when you set up proxy users. Otherwise, the plugin cannot tell how to map the name of PAM groups to the proper proxied user name.
If your MySQL installation has anonymous users, they might conflict with the default proxy user. For more information about this problem, and ways of dealing with it, see Default Proxy User and Anonymous User Conflicts.
Create the proxied accounts that will be used to access the databases:
CREATE USER 'developer'@'localhost' IDENTIFIED BY 'very secret password
'; GRANT ALL PRIVILEGES ON mydevdb.* TO 'developer'@'localhost'; CREATE USER 'data_entry'@'localhost' IDENTIFIED BY 'very secret password
'; GRANT ALL PRIVILEGES ON mydb.* TO 'data_entry'@'localhost';
If you do not let anyone know the passwords for these
accounts, other users cannot use them to connect directly
to the MySQL server. Instead, it is expected that users
will authenticate using PAM and that they will use the
developer
or
data_entry
account by proxy based on
their PAM group.
Grant the PROXY
privilege
to the proxy account for the proxied accounts:
GRANT PROXY ON 'developer'@'localhost' TO ''@''; GRANT PROXY ON 'data_entry'@'localhost' TO ''@'';
Connect to the MySQL server using the mysql command-line client. For example:
mysql --user=antonio --password=verysecret --enable-cleartext-plugin mydb
The server authenticates the connection using the
''@''
account. The privileges
antonio
will have depends on what PAM
groups he is a member of. If antonio
is a
member of the root
PAM group, the PAM
plugin maps root
to the
developer
MySQL user name and returns
that name to the server. The server verifies that
''@''
has the
PROXY
privilege for
developer
and permits the connection.
the following query should return output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
+-------------------+---------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-------------------+---------------------+--------------+
| antonio@localhost | developer@localhost | ''@'' |
+-------------------+---------------------+--------------+
This demonstrates that antonio
uses the
privileges granted to the developer
MySQL account, and that proxying occurred through the
default proxy user account.
If antonio
is not a member of the
root
PAM group but is a member of the
users
group, a similar process occurs,
but the plugin maps user
group
membership to the data_entry
MySQL user
name and returns that name to the server. In this case,
antonio
uses the privileges of the
data_entry
MySQL account:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
+-------------------+----------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-------------------+----------------------+--------------+
| antonio@localhost | data_entry@localhost | ''@'' |
+-------------------+----------------------+--------------+
The PAM authentication plugin checks at initialization time
whether the AUTHENTICATION_PAM_LOG
environment value is set (the value does not matter). If so,
the plugin enables logging of diagnostic messages to the
standard output. These messages may be helpful for debugging
PAM-related problems that occur when the plugin performs
authentication.
Some messages include reference to PAM plugin source files and line numbers, which enables plugin actions to be tied more closely to the location in the code where they occur.
The following transcript demonstrates the kind of information produced by enabling logging. It resulted from a successful proxy authentication attempt.
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
The Windows authentication plugin is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see http://www.mysql.com/products/.
As of MySQL 5.7.9, 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:
External authentication: The plugin enables MySQL Server to accept connections from users defined outside the MySQL grant tables.
Proxy user support: The plugin can return to MySQL a user
name different from the client user. This means that the
plugin can return the MySQL user that defines the privileges
the external Windows-authenticated user should have. For
example, a Windows user named joe
can
connect and have the privileges of the MySQL user named
developer
.
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 6.4.1.6.1, “Installing the Windows Authentication Plugin”.
Table 6.13 MySQL Windows Authentication Plugin
Server-side plugin name | authentication_windows |
Client-side plugin name | authentication_windows_client |
Library object file name | authentication_windows.dll |
The library file includes only the server-side plugin. 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 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.7 (see http://www.mysql.com/support/supportedplatforms/database.html).
For general information about pluggable authentication in MySQL, see Section 6.3.8, “Pluggable Authentication”. For proxy user information, see Section 6.3.9, “Proxy Users”.
The Windows authentication plugin must be installed 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 location of the plugin directory.
To enable the plugin, start the server with the
--plugin-load
option. For
example, put these lines in your my.ini
file:
[mysqld] plugin-load=authentication_windows.dll
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement. See Section 5.1.8.2, “Obtaining Server Plugin Information”.
To associate a MySQL account with the Windows authentication
plugin, use the plugin name
authentication_windows
in the
IDENTIFIED WITH
clause of
CREATE USER
or
GRANT
statement that creates
the account.
The Windows authentication plugin supports the use of MySQL accounts such that users who have logged in to Windows can connect to the MySQL server without having to specify an additional password. It is assumed that the server-side plugin is enabled, as described previously. Once the DBA has enabled the server-side plugin and set up accounts to use it, clients can connect using those accounts with no other setup required on their part.
To refer to the Windows authentication plugin in the
IDENTIFIED WITH
clause of a
CREATE USER
or
GRANT
statement, use the name
authentication_windows
. Suppose that the
Windows users Rafal
and
Tasha
should be permitted to connect to
MySQL, as well as any users in the
Administrators
or Power
Users
group. To set this up, create a MySQL account
named sql_admin
that uses the Windows
plugin for authentication:
CREATE USER sql_admin IDENTIFIED WITH authentication_windows AS 'Rafal, Tasha, Administrators, "Power Users"';
The plugin name is authentication_windows
.
The string following the AS
keyword is the
authentication string. It specifies that the Windows users
named Rafal
or Tasha
are
permitted to authenticate to the server as the MySQL user
sql_admin
, as are any Windows users in the
Administrators
or Power
Users
group. The latter group name contains a space,
so it must be quoted with double quote characters.
After you create the sql_admin
account, a
user who has logged in to Windows can attempt to connect to
the server using that account:
C:\> mysql --user=sql_admin
No password is required here. The
authentication_windows
plugin uses the
Windows security API to check which Windows user is
connecting. If that user is named Rafal
or
Tasha
, or is in the
Administrators
or Power
Users
group, the server grants access and the client
is authenticated as sql_admin
and has
whatever privileges are granted to the
sql_admin
account. Otherwise, the server
denies access.
Authentication string syntax for the Windows authentication plugin follows these rules:
The string consists of one or more user mappings separated by commas.
Each user mapping associates a Windows user or group name with a MySQL user name:
win_user_or_group_name=mysql_user_name
win_user_or_group_name
For the latter syntax, with no
mysql_user_name
value given,
the implicit value is the MySQL user created by the
CREATE USER
statement.
Thus, these statements are equivalent:
CREATE USER sql_admin IDENTIFIED WITH authentication_windows AS 'Rafal, Tasha, Administrators, "Power Users"'; CREATE USER sql_admin IDENTIFIED WITH authentication_windows AS 'Rafal=sql_admin, Tasha=sql_admin, Administrators=sql_admin, "Power Users"=sql_admin';
Each backslash ('\'
) in a value must be
doubled because backslash is the escape character in MySQL
strings.
Leading and trailing spaces not inside double quotation marks are ignored.
Unquoted win_user_or_group_name
and mysql_user_name
values can
contain anything except equal sign, comma, or space.
If a win_user_or_group_name
and
or mysql_user_name
value is
quoted with double quotation marks, everything between the
quotation marks is part of the value. This is necessary,
for example, if the name contains space characters. All
characters within double quotes are legal except double
quotation mark and backslash. To include either character,
escape it with a backslash.
win_user_or_group_name
values
use conventional syntax for Windows principals, either
local or in a domain. Examples (note the doubling of
backslashes):
domain\\user .\\user domain\\group .\\group BUILTIN\\WellKnownGroup
When invoked by the server to authenticate a client, the
plugin scans the authentication string left to right for a
user or group match to the Windows user. If there is a match,
the plugin returns the corresponding
mysql_user_name
to the MySQL
server. If there is no match, authentication fails.
A user name match takes preference over a group name match.
Suppose that the Windows user named
win_user
is a member of
win_group
and the authentication string
looks like this:
'win_group = sql_user1, win_user = sql_user2'
When win_user
connects to the MySQL server,
there is a match both to win_group
and to
win_user
. The plugin authenticates the user
as sql_user2
because the more-specific user
match takes precedence over the group match, even though the
group is listed first in the authentication string.
Windows authentication always works for connections from the same computer on which the server is running. For cross-computer connections, both computers must be registered with Windows Active Directory. If they are in the same Windows domain, it is unnecessary to specify a domain name. It is also possible to permit connections from a different domain, as in this example:
CREATE USER sql_accounting IDENTIFIED WITH authentication_windows AS 'SomeDomain\\Accounting';
Here SomeDomain
is the name of the other
domain. The backslash character is doubled because it is the
MySQL escape character within strings.
MySQL supports the concept of proxy users whereby a client can connect and authenticate to the MySQL server using one account but while connected has the privileges of another account (see Section 6.3.9, “Proxy Users”). Suppose that you want Windows users to connect using a single user name but be mapped based on their Windows user and group names onto specific MySQL accounts as follows:
The local_user
and
MyDomain\domain_user
local and domain
Windows users should map to the
local_wlad
MySQL account.
Users in the MyDomain\Developers
domain
group should map to the local_dev
MySQL
account.
Local machine administrators should map to the
local_admin
MySQL account.
To set this up, create a proxy account for Windows users to
connect to, and configure this account so that users and
groups map to the appropriate MySQL accounts
(local_wlad
, local_dev
,
local_admin
). In addition, grant the MySQL
accounts the privileges appropriate to the operations they
need to perform. The following instructions use
win_proxy
as the proxy account, and
local_wlad
, local_dev
,
and local_admin
as the proxied accounts.
Create the proxy MySQL account:
CREATE USER win_proxy IDENTIFIED WITH authentication_windows AS 'local_user = local_wlad, MyDomain\\domain_user = local_wlad, MyDomain\\Developers = local_dev, BUILTIN\\Administrators = local_admin';
For proxying to work, the proxied accounts must exist, so create them:
CREATE USER local_wlad IDENTIFIED BY 'wlad_pass'; CREATE USER local_dev IDENTIFIED BY 'dev_pass'; CREATE USER local_admin IDENTIFIED BY 'admin_pass';
If you do not let anyone know the passwords for these accounts, other users cannot use them to connect directly to the MySQL server.
You should also issue GRANT
statements (not shown) that grant each proxied account the
privileges it needs.
The proxy account must have the
PROXY
privilege for each of
the proxied accounts:
GRANT PROXY ON local_wlad TO win_proxy; GRANT PROXY ON local_dev TO win_proxy; GRANT PROXY ON local_admin TO win_proxy;
Now the Windows users local_user
and
MyDomain\domain_user
can connect to the
MySQL server as win_proxy
and when
authenticated have the privileges of the account given in the
authentication string—in this case,
local_wlad
. A user in the
MyDomain\Developers
group who connects as
win_proxy
has the privileges of the
local_dev
account. A user in the
BUILTIN\Administrators
group has the
privileges of the local_admin
account.
To configure authentication so that all Windows users who do
not have their own MySQL account go through a proxy account,
substitute the default proxy user (''@''
)
for win_proxy
in the preceding
instructions. For information about the default proxy user,
see Section 6.3.9, “Proxy Users”.
If your MySQL installation has anonymous users, they might conflict with the default proxy user. For more information about this problem, and ways of dealing with it, see Default Proxy User and Anonymous User Conflicts.
To use the Windows authentication plugin with Connector/Net connection strings in Connection/Net 6.4.4 and higher, see Using the Windows Native Authentication Plugin.
Additional control over the Windows authentication plugin is
provided by the
authentication_windows_use_principal_name
and
authentication_windows_log_level
system variables. See
Section 5.1.4, “Server System Variables”.
The mysql_no_login
server-side authentication
plugin prevents all client connections to any account that uses
it. Use cases for such a plugin includes accounts that must be
able to execute stored programs and views with elevated
privileges without exposing those privileges to ordinary users,
and proxy accounts that should never permit direct login.
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 6.3.8, “Pluggable Authentication”.
Table 6.14 MySQL “No Login” Authentication Plugin
Server-side plugin name | mysql_no_login |
Client-side plugin name | None |
Library object file name | mysql_no_login.so |
An account that authenticates using
mysql_no_login
may be used as the
DEFINER
for stored program and view objects.
If such an object definition also includes SQL SECURITY
DEFINER
, it executes with that account's privileges.
DBAs can use this behavior to provide access to confidential or
sensitive data that is exposed only through well-controlled
interfaces.
The following example provides a simple illustration of these
principles. It defines an account that does not permit client
connections, and associates with it a view that exposes only
certain columns of the mysql.user
table:
CREATE DATABASE nologindb; CREATE USER 'nologin'@'localhost' IDENTIFIED WITH mysql_no_login; GRANT ALL ON nologindb.* TO 'nologin'@'localhost'; GRANT SELECT ON mysql.user TO 'nologin'@'localhost'; CREATE DEFINER = 'nologin'@'localhost' SQL SECURITY DEFINER VIEW nologindb.myview AS SELECT User, Host FROM mysql.user;
To provide protected access to the view to ordinary users, do this:
GRANT SELECT ON nologindb.myview TO 'ordinaryuser'@'localhost';
Now the ordinary user can use the view to access the limited information it presents:
SELECT * FROM nologindb.myview;
Attempts by the user to access columns other than those exposed by the view result in an error.
Because the nologin
account cannot be used
directly, the operations required to set up objects that it
uses must be performed by root
or similar
account with the privileges required to create the objects and
set DEFINER
values.
An account that authenticates using
mysql_no_login
may be used as a base user for
proxy accounts:
CREATE USER 'proxy_base'@'localhost' IDENTIFIED WITH mysql_no_login;
... grant to 'proxy_base'@'localhost' any privileges it requires ...
GRANT PROXY ON 'proxy_base'@'localhost' TO 'real_user'@'localhost';
This enables clients to access MySQL through the proxy account but not to bypass the proxy mechanism by connecting directly as the proxy user.
For general information about pluggable authentication in MySQL, see Section 6.3.8, “Pluggable Authentication”.
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.
Table 6.15 MySQL Cleartext Authentication Plugin
Server-side plugin name | None, see discussion |
Client-side plugin name | mysql_clear_password |
Library object file name | None (plugin is built in) |
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 6.1.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 6.4.1.5, “The PAM Authentication Plugin”.)
For general information about pluggable authentication in MySQL, see Section 6.3.8, “Pluggable Authentication”.
Sending passwords in clear text may be a security problem in some configurations. To avoid problems if there is any possibility that the password would be intercepted, clients should connect to MySQL Server using a method that protects the password. Possibilities include SSL (see Section 6.3.11, “Using Secure Connections”), IPsec, or a private network.
To make inadvertent use of this plugin less likely, it is required that clients explicitly enable it. This can be done several ways:
Set the LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN
environment variable to a value that begins with
1
, Y
, or
y
. This enables the plugin for all client
connections.
The mysql, mysqladmin,
and mysqlslap client programs support an
--enable-cleartext-plugin
option that
enables the plugin on a per-invocation basis.
The mysql_options()
C API
function supports a
MYSQL_ENABLE_CLEARTEXT_PLUGIN
option that
enables the plugin on a per-connection basis. Also, any
program that uses libmysqlclient
and
reads option files can enable the plugin by including an
enable-cleartext-plugin
option in an
option group read by the client library.
A server-side authentication plugin is available that authenticates clients that connect from the local host through the Unix socket file.
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 6.3.8, “Pluggable Authentication”.
Table 6.16 MySQL Socket Peer-Credential Authentication Plugin
Server-side plugin name | auth_socket |
Client-side plugin name | None, see discussion |
Library object file name | auth_socket.so |
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 socket user name matches the MySQL
user name specified by the client program to the server. As of
MySQL 5.7.6, if the names do not match, the plugin also checks
whether the socket user name matches the name specified in the
authentication_string
column of the
mysql.user
table row. If a match is found,
the plugin permits the connection.
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 6.3.8, “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 6.3.8, “Pluggable Authentication”.
Table 6.17 MySQL Test Authentication Plugin
Server-side plugin name | test_plugin_server |
Client-side plugin name | auth_test_plugin |
Library object file name | auth_test_plugin.so |
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 6.3.8, “Pluggable Authentication”.
The validate_password
plugin can be used to
test passwords and improve security. This plugin implements two
capabilities:
In statements that assign a password supplied as a cleartext
value, the value is checked against the current password
policy and rejected if it is weak (the statement returns an
ER_NOT_VALID_PASSWORD
error).
This affects the ALTER USER
,
CREATE USER
,
GRANT
, and
SET PASSWORD
statements.
Passwords given as arguments to the
PASSWORD()
and
OLD_PASSWORD()
functions are
checked as well.
The strength of potential passwords can be assessed using the
VALIDATE_PASSWORD_STRENGTH()
SQL function, which takes a password argument and returns an
integer from 0 (weak) to 100 (strong).
For example, the cleartext password in the following statement is checked. Under the default password policy, which requires passwords to be at least 8 characters long, the password is weak and the statement produces an error:
mysql> ALTER USER USER() IDENTIFIED BY 'abc';
ERROR 1819 (HY000): Your password does not satisfy the current policy
requirements
Passwords specified as already hashed values are not checked because the original password value is not available:
mysql>ALTER USER 'jeffrey'@'localhost'
->IDENTIFIED WITH mysql_native_password
->AS '*0D3CED9BEC10A777AEC23CCC353A8C08A633045E';
Query OK, 0 rows affected (0.01 sec)
The parameters that control password checking are available as the
values of the system variables having names of the form
validate_password_
.
These variables can be modified to configure password checking;
see Section 6.4.2.2, “Password Validation Plugin Options and Variables”.
xxx
The three levels of password checking are LOW
,
MEDIUM
, and STRONG
. The
default is MEDIUM
; to change this, modify the
value of
validate_password_policy
. The
policies implement increasingly strict password tests. The
following descriptions refer to default parameter values; these
can be modified by changing the appropriate system variables.
LOW
policy tests password length only.
Passwords must be at least 8 characters long.
MEDIUM
policy adds the conditions that
passwords must contain at least 1 numeric character, 1
lowercase and uppercase character, and 1 special
(nonalphanumeric) character.
STRONG
policy adds the condition that
password substrings of length 4 or longer must not match words
in the dictionary file, if one has been specified.
If the validate_password
plugin is not
installed, the
validate_password_
system variables are not available, passwords in statements are
not checked, and
xxx
VALIDATE_PASSWORD_STRENGTH()
always
returns 0. For example, accounts can be assigned passwords shorter
than 8 characters.
The password-validation plugin is named
validate_password
. To be usable by the
server, the plugin library object 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 location of the plugin directory.
To load the plugin at server startup, use the
--plugin-load
option to name the
object file that contains the plugin. With this plugin-loading
method, the option must be given each time the server starts.
For example, put these lines in your my.cnf
file:
[mysqld] plugin-load=validate_password.so
If object files have a suffix different from
.so
on your system, substitute the correct
suffix (for example, .dll
on Windows).
Alternatively, to register the plugin at runtime, use this statement (changing the extension as necessary):
mysql> INSTALL PLUGIN validate_password SONAME 'validate_password.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.
If the plugin has been previously registered with
INSTALL PLUGIN
or is loaded with
--plugin-load
, you can use the
--validate-password
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=validate_password.so validate-password=FORCE_PLUS_PERMANENT
If it is desired to prevent the server from running without the
password-validation plugin, use
--validate-password
with a value
of FORCE
or
FORCE_PLUS_PERMANENT
to force server startup
to fail if the plugin does not initialize successfully.
For general information about installing or uninstalling
plugins, see Section 5.1.8.1, “Installing and Uninstalling Plugins”. To verify
plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table or
use the SHOW PLUGINS
statement.
See Section 5.1.8.2, “Obtaining Server Plugin Information”.
To control the activation of the
validate_password
plugin, use this option:
Command-Line Format | --validate-password[=value] | ||
Permitted Values | Type | enumeration | |
Default | ON | ||
Valid Values | ON | ||
OFF | |||
FORCE | |||
FORCE_PLUS_PERMANENT |
This option controls how the server loads the
validate_password
plugin at startup. The
value should be one of those available for plugin-loading
options, as described in
Section 5.1.8.1, “Installing and Uninstalling Plugins”. For example,
--validate-password=FORCE_PLUS_PERMANENT
tells the server to load the plugin at startup and prevents
it from being removed while the server is running.
This option is available only if the
validate_password
plugin has been
previously registered with INSTALL
PLUGIN
or is loaded with
--plugin-load
. See
Section 6.4.2.1, “Password Validation Plugin Installation”.
If the validate_password
plugin is installed,
it exposes several system variables that indicate the parameters
that control password checking:
mysql> SHOW VARIABLES LIKE 'validate_password%';
+--------------------------------------+--------+
| Variable_name | Value |
+--------------------------------------+--------+
| validate_password_dictionary_file | |
| validate_password_length | 8 |
| validate_password_mixed_case_count | 1 |
| validate_password_number_count | 1 |
| validate_password_policy | MEDIUM |
| validate_password_special_char_count | 1 |
+--------------------------------------+--------+
To change how passwords are checked, you can set any of these variables at server startup, and most of them at runtime. The following list describes the meaning of each variable.
validate_password_dictionary_file
System Variable (<= 5.7.7) | Name | validate_password_dictionary_file | |
Variable Scope | Global | ||
Dynamic Variable | No | ||
System Variable (>= 5.7.8) | Name | validate_password_dictionary_file | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | file name |
The path name of the dictionary file used by the
validate_password
plugin for checking
passwords. This variable is unavailable unless that plugin
is installed.
By default, this variable has an empty value and dictionary
checks are not performed. To enable dictionary checks, you
must set this variable to a nonempty value. If the file is
named as a relative path, it is interpreted relative to the
server data directory. Its contents should be lowercase, one
word per line. Contents are treated as having a character
set of utf8
. The maximum permitted file
size is 1MB.
For the dictionary file to be used during password checking,
the password policy must be set to 2
(STRONG
); see the description of the
validate_password_policy
system variable. Assuming that is true, each substring of
the password of length 4 up to 100 is compared to the words
in the dictionary file. Any match causes the password to be
rejected. Comparisons are not case sensitive.
For
VALIDATE_PASSWORD_STRENGTH()
the password is checked against all policies, including
STRONG
, so the strength assessment
includes the dictionary check regardless of the
validate_password_policy
value.
Changes to the dictionary file while the server is running require a restart for the server to recognize the changes.
Before MySQL 5.7.8, changes to the dictionary file while the
server is running require a restart for the server to
recognize the changes. As of MySQL 5.7.8,
validate_password_dictionary_file
can be set at runtime and assigning a value causes the named
file to be read without a restart.
System Variable | Name | validate_password_length | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | integer | |
Default | 8 | ||
Min Value | 0 |
The minimum number of characters that passwords checked by
the validate_password
plugin must have.
This variable is unavailable unless that plugin is
installed.
The
validate_password_length
minimum value is a function of several other related system
variables. The server will not set the value less than the
value of this expression:
validate_password_number_count + validate_password_special_char_count + (2 * validate_password_mixed_case_count)
If the validate_password
plugin adjusts
the value of
validate_password_length
due to the preceding constraint, it writes a message to the
error log.
validate_password_mixed_case_count
System Variable | Name | validate_password_mixed_case_count | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | integer | |
Default | 1 | ||
Min Value | 0 |
The minimum number of lowercase and uppercase characters
that passwords checked by the
validate_password
plugin must have if the
password policy is MEDIUM
or stronger.
This variable is unavailable unless that plugin is
installed.
validate_password_number_count
System Variable | Name | validate_password_number_count | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | integer | |
Default | 1 | ||
Min Value | 0 |
The minimum number of numeric (digit) characters that
passwords checked by the
validate_password
plugin must have if the
password policy is MEDIUM
or stronger.
This variable is unavailable unless that plugin is
installed.
System Variable | Name | validate_password_policy | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | enumeration | |
Default | 1 | ||
Valid Values | 0 | ||
1 | |||
2 |
The password policy enforced by the
validate_password
plugin. This variable
is unavailable unless that plugin is installed.
The
validate_password_policy
value can be specified using numeric values 0, 1, 2, or the
corresponding symbolic values LOW
,
MEDIUM
, STRONG
. The
following table describes the tests performed for each
policy. For the length test, the required length is the
value of the
validate_password_length
system variable. Similarly, the required values for the
other tests are given by other
validate_password_
variables.
xxx
Policy | Tests Performed |
---|---|
0 or LOW | Length |
1 or MEDIUM | Length; numeric, lowercase/uppercase, and special characters |
2 or STRONG | Length; numeric, lowercase/uppercase, and special characters; dictionary file |
validate_password_special_char_count
System Variable | Name | validate_password_special_char_count | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | integer | |
Default | 1 | ||
Min Value | 0 |
The minimum number of nonalphanumeric characters that
passwords checked by the
validate_password
plugin must have if the
password policy is MEDIUM
or stronger.
This variable is unavailable unless that plugin is
installed.
If the validate_password
plugin is installed,
it exposes several status variables that provide operational
information:
mysql> SHOW STATUS LIKE 'validate_password%';
+-----------------------------------------------+---------------------+
| Variable_name | Value |
+-----------------------------------------------+---------------------+
| validate_password_dictionary_file_last_parsed | 2015-06-29 11:08:51 |
| validate_password_dictionary_file_words_count | 1902 |
+-----------------------------------------------+---------------------+
The following list describes the meaning of each variable.
validate_password_dictionary_file_last_parsed
When the dictionary file was last parsed.
This variable was added in MySQL 5.7.8.
validate_password_dictionary_file_words_count
The number of words read from the dictionary file.
This variable was added in MySQL 5.7.8.
As of MySQL 5.7.11, the InnoDB
storage engine
uses the keyring to store its key for tablespace encryption. The
keyring is implemented by the keyring_file
plugin library file located in the directory named by the
plugin_dir
system variable. The
file base name is keyring_file
. The file name
suffix differs per platform (for example, .so
for Unix and Unix-like systems, .dll
for
Windows).
To enable the InnoDB
storage engine to use the
keyring for tablespace encryption, the
keyring_file
plugin must be loaded early to
ensure that it is available prior to InnoDB
initialization.
To load the plugin, use the
--early-plugin-load
option to name
the plugin library file. For example, on platforms where the
plugin library file suffix is .so
, use these
lines in the server my.cnf
file:
[mysqld] early-plugin-load=keyring_file.so
If object files have a suffix different from
.so
on your system, substitute the correct
suffix (for example, .dll
on Windows).
As of MySQL 5.7.12, the default
--early-plugin-load
value is empty.
To load the keyring_file
plugin, you must use
an explicit --early-plugin-load
option with a nonempty value.
In MySQL 5.7.11, the default
--early-plugin-load
value was the
name of the keyring_file
plugin library file,
so that plugin was loaded by default. The change of default
value in MySQL 5.7.12 introduces an incompatibility for upgrades
from 5.7.11 to 5.7.12 or higher that requires administrators who
have encrypted InnoDB
tablespaces to take
explicit action to ensure continued loading of the
keyring_file
plugin; tablespace encryption
requires that plugin to be loaded prior to
InnoDB
initialization. To do this, start the
server with an explicit
--early-plugin-load
option that
names the plugin library file, as just described.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table or
use the SHOW PLUGINS
statement. See
Section 5.1.8.2, “Obtaining Server Plugin Information”.
MySQL Enterprise Audit is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see http://www.mysql.com/products/.
As of MySQL 5.7.9, MySQL Enterprise Edition includes MySQL
Enterprise Audit, implemented using a server plugin named
audit_log
. MySQL Enterprise Audit uses the open
MySQL Audit API to enable standard, policy-based monitoring and
logging of connection and query activity executed on specific
MySQL servers. Designed to meet the Oracle audit specification,
MySQL Enterprise Audit provides an out of box, easy to use
auditing and compliance solution for applications that are
governed by both internal and external regulatory guidelines.
When installed, the audit plugin enables MySQL Server to produce a log file containing an audit record of server activity. The log contents include when clients connect and disconnect, and what actions they perform while connected, such as which databases and tables they access.
After you install the plugin (see
Section 6.4.4.1, “Installing the Audit Log Plugin”), it writes an
audit log file. By default, the file is named
audit.log
in the server data directory. To
change the name of the file, set the
audit_log_file
system variable at
server startup.
Audit log file contents are not encrypted. See Section 6.4.4.2, “Audit Log Plugin Security Considerations”.
The audit log file is written in XML, with auditable events
encoded as <AUDIT_RECORD>
elements. To
select the file format, set the
audit_log_format
system variable
at server startup. For details on file format and contents, see
Section 6.4.4.3, “The Audit Log File”.
To control what information audit_log
writes to
its log file, set the
audit_log_policy
system variable.
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.
For more information about controlling how logging occurs, see Section 6.4.4.4, “Audit Log Plugin Logging Control”. For descriptions of the parameters used to configure the audit log plugin, see Section 6.4.4.6, “Audit Log Plugin Options and Variables”.
If the audit_log
plugin is enabled, the
Performance Schema (see Chapter 22, MySQL Performance Schema) has
instrumentation for the audit log plugin. To identify the relevant
instruments, use this query:
SELECT NAME FROM performance_schema.setup_instruments WHERE NAME LIKE '%/alog/%';
The audit log plugin is named audit_log
. To
be usable by the server, the plugin library object 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 location of the plugin directory.
To load the plugin at server startup, use the
--plugin-load
option to name the
object 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:
[mysqld] plugin-load=audit_log.so
If object files have a suffix different from
.so
on your system, substitute the correct
suffix (for example, .dll
on Windows).
Alternatively, to register the plugin at runtime, use this statement (changing the suffix as necessary):
mysql> 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.
If the plugin is loaded with
--plugin-load
or has been
previously registered with INSTALL
PLUGIN
, you can use the --audit-log
option at server startup to control plugin activation. For
example, to load the plugin 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 general information about installing plugins, see
Section 5.1.8, “Server Plugins”. To verify plugin installation,
examine the
INFORMATION_SCHEMA.PLUGINS
table or
use the SHOW PLUGINS
statement.
See Section 5.1.8.2, “Obtaining Server Plugin Information”.
Audit log file contents are not encrypted. See Section 6.4.4.2, “Audit Log Plugin Security Considerations”.
For additional information about the parameters used to
configure operation of the audit_log
plugin,
see Section 6.4.4.6, “Audit Log Plugin Options and Variables”.
Contents of the audit log file produced by the
audit_log
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 6.4.4.2, “Audit Log Plugin 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 of which
provides information about an audited event.
MySQL 5.7 changed audit log file output to a new
format, 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
NEW
).
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:
Stop the server.
Rename the current audit log file manually.
Restart the server with the new value of
audit_log_format
. The audit
log plugin will create a new log file, which will contain
log entries in the selected format.
Here is a sample log file in the default (new) format, reformatted slightly for readability:
<?xml version="1.0" encoding="UTF-8"?> <AUDIT> <AUDIT_RECORD> <TIMESTAMP>2013-09-17T15:03:24 UTC</TIMESTAMP> <RECORD_ID>1_2013-09-17T15:03:24</RECORD_ID> <NAME>Audit</NAME> <SERVER_ID>1</SERVER_ID> <VERSION>1</VERSION> <STARTUP_OPTIONS>/usr/local/mysql/bin/mysqld --socket=/usr/local/mysql/mysql.sock --port=3306</STARTUP_OPTIONS> <OS_VERSION>x86_64-osx10.6</OS_VERSION> <MYSQL_VERSION>5.7.2-m12-log</MYSQL_VERSION> </AUDIT_RECORD> <AUDIT_RECORD> <TIMESTAMP>2013-09-17T15:03:40 UTC</TIMESTAMP> <RECORD_ID>2_2013-09-17T15:03:24</RECORD_ID> <NAME>Connect</NAME> <CONNECTION_ID>2</CONNECTION_ID> <STATUS>0</STATUS> <STATUS_CODE>0</STATUS_CODE> <USER>root</USER> <OS_LOGIN></OS_LOGIN> <HOST>localhost</HOST> <IP>127.0.0.1</IP> <COMMAND_CLASS>connect</COMMAND_CLASS> <PRIV_USER>root</PRIV_USER> <PROXY_USER></PROXY_USER> <DB>test</DB> </AUDIT_RECORD> ... <AUDIT_RECORD> <TIMESTAMP>2013-09-17T15:03:41 UTC</TIMESTAMP> <RECORD_ID>4_2013-09-17T15:03:24</RECORD_ID> <NAME>Query</NAME> <CONNECTION_ID>2</CONNECTION_ID> <STATUS>0</STATUS> <STATUS_CODE>0</STATUS_CODE> <USER>root[root] @ localhost [127.0.0.1]</USER> <OS_LOGIN></OS_LOGIN> <HOST>localhost</HOST> <IP>127.0.0.1</IP> <COMMAND_CLASS>drop_table</COMMAND_CLASS> <SQLTEXT>DROP TABLE IF EXISTS t</SQLTEXT> </AUDIT_RECORD> <AUDIT_RECORD> <TIMESTAMP>2013-09-17T15:03:41 UTC</TIMESTAMP> <RECORD_ID>5_2013-09-17T15:03:24</RECORD_ID> <NAME>Query</NAME> <CONNECTION_ID>2</CONNECTION_ID> <STATUS>0</STATUS> <STATUS_CODE>0</STATUS_CODE> <USER>root[root] @ localhost [127.0.0.1]</USER> <OS_LOGIN></OS_LOGIN> <HOST>localhost</HOST> <IP>127.0.0.1</IP> <COMMAND_CLASS>create_table</COMMAND_CLASS> <SQLTEXT>CREATE TABLE t (i INT)</SQLTEXT> </AUDIT_RECORD> ... <AUDIT_RECORD> <TIMESTAMP>2013-09-17T15:03:41 UTC</TIMESTAMP> <RECORD_ID>7_2013-09-17T15:03:24</RECORD_ID> <NAME>Quit</NAME> <CONNECTION_ID>2</CONNECTION_ID> <STATUS>0</STATUS> <STATUS_CODE>0</STATUS_CODE> <USER></USER> <OS_LOGIN></OS_LOGIN> <HOST></HOST> <IP></IP> <COMMAND_CLASS>connect</COMMAND_CLASS> </AUDIT_RECORD> ... <AUDIT_RECORD> <TIMESTAMP>2013-09-17T15:03:47 UTC</TIMESTAMP> <RECORD_ID>9_2013-09-17T15:03:24</RECORD_ID> <NAME>Shutdown</NAME> <CONNECTION_ID>3</CONNECTION_ID> <STATUS>0</STATUS> <STATUS_CODE>0</STATUS_CODE> <USER>root[root] @ localhost [127.0.0.1]</USER> <OS_LOGIN></OS_LOGIN> <HOST>localhost</HOST> <IP>127.0.0.1</IP> <COMMAND_CLASS></COMMAND_CLASS> </AUDIT_RECORD> <AUDIT_RECORD> <TIMESTAMP>2013-09-17T15:03:47 UTC</TIMESTAMP> <RECORD_ID>10_2013-09-17T15:03:24</RECORD_ID> <NAME>Quit</NAME> <CONNECTION_ID>3</CONNECTION_ID> <STATUS>0</STATUS> <STATUS_CODE>0</STATUS_CODE> <USER></USER> <OS_LOGIN></OS_LOGIN> <HOST></HOST> <IP></IP> <COMMAND_CLASS>connect</COMMAND_CLASS> </AUDIT_RECORD> <AUDIT_RECORD> <TIMESTAMP>2013-09-17T15:03:49 UTC</TIMESTAMP> <RECORD_ID>11_2013-09-17T15:03:24</RECORD_ID> <NAME>NoAudit</NAME> <SERVER_ID>1</SERVER_ID> </AUDIT_RECORD> </AUDIT>
Here is a sample log file in the 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.6.10-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>
Elements within <AUDIT_RECORD>
elements
have these characteristics:
Some elements appear in every
<AUDIT_RECORD>
element, but many
are optional and do not necessarily appear in every element.
Order of elements within an
<AUDIT_RECORD>
element is not
guaranteed.
Element values are not fixed length. Long values may be truncated as indicated in the element descriptions given later.
The <
, >
,
"
, and &
characters are encoded as <
,
>
, "
,
and &
, respectively. NUL bytes
(U+00) are encoded as the ?
character.
Characters not valid as XML characters are encoded using numeric character references. Valid XML characters are:
#x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
Every <AUDIT_RECORD>
element contains a
set of mandatory elements. Other optional elements may appear,
depending on the audit record type.
The following elements are mandatory in every
<AUDIT_RECORD>
element:
<NAME>
A string representing the type of instruction that generated the audit event, such as a command that the server received from a client.
Example:
<NAME>Query</NAME>
Some common <NAME>
values:
Audit When auditing starts, which may be server startup time Connect When a client connects, also known as logging in Query An SQL statement (executed directly) Prepare Preparation of an SQL statement; usually followed by Execute Execute Execution of an SQL statement; usually follows Prepare Shutdown Server shutdown Quit When a client disconnects NoAudit Auditing has been turned off
The possible values are Audit
,
Binlog Dump
, Change
user
, Close stmt
,
Connect Out
, Connect
,
Create DB
, Daemon
,
Debug
, Delayed insert
,
Drop DB
, Execute
,
Fetch
, Field List
,
Init DB
, Kill
,
Long Data
, NoAudit
,
Ping
, Prepare
,
Processlist
, Query
,
Quit
, Refresh
,
Register Slave
, Reset
stmt
, Set option
,
Shutdown
, Sleep
,
Statistics
, Table
Dump
, Time
.
With the exception of Audit
and
NoAudit
, these values correspond to the
COM_
command values listed in the
xxx
mysql_com.h
header file. For example,
Create DB
and Shutdown
correspond to COM_CREATE_DB
and
COM_SHUTDOWN
, respectively.
<RECORD_ID>
A unique identifier for the audit record. The value is
composed from a sequence number and timestamp, in the format
.
The sequence number is initialized to the size of the audit
log file at the time the audit log plugin opens it and
increments by 1 for each record logged. The timestamp is a
UTC value in
SEQ_TIMESTAMP
format indicating the time when the audit log plugin opened
the file.
yyyy-mm-dd
Thh:mm:ss
Example:
<RECORD_ID>28743_2013-09-18T21:03:24</RECORD_ID>
<TIMESTAMP>
The date and time that the audit event was generated. For
example, the event corresponding to execution of an SQL
statement received from a client has a
<TIMESTAMP>
value occurring after
the statement finishes, not when it is received. The value
has the format
(with yyyy-mm-dd
Thh:mm:ss
UTCT
, no decimals). The
format includes a time zone specifier at the end. The time
zone is always UTC.
Example:
<TIMESTAMP>2013-09-17T15:03:49 UTC</TIMESTAMP>
The following elements are optional in
<AUDIT_RECORD>
elements. Many of them
occur only with specific <NAME>
values.
<COMMAND_CLASS>
A string that indicates the type of action performed.
Example:
<COMMAND_CLASS>drop_table</COMMAND_CLASS>
The values come from the com_status_vars
array in the sql/mysqld.cc
file in a
MySQL source distribution. They correspond to the status
variables displayed by this statment:
SHOW STATUS LIKE 'Com%';
<CONNECTION_ID>
An unsigned integer representing the client connection
identifier. This is the same as the
CONNECTION_ID()
function
value within the session.
Example:
<CONNECTION_ID>127</CONNECTION_ID>
<DB>
A string representing the default database name. This
element appears only if the <NAME>
value is Connect
or Change
user
.
<HOST>
A string representing the client host name. This element
appears only if the <NAME>
value is
Connect
, Change user
,
or Query
.
Example:
<HOST>localhost</HOST>
<IP>
A string representing the client IP address. This element
appears only if the <NAME>
value is
Connect
, Change user
,
or Query
.
Example:
<IP>127.0.0.1</IP>
<MYSQL_VERSION>
A string representing the MySQL server version. This is the
same as the value of the
VERSION()
function or
version
system variable.
This element appears only if the
<NAME>
value is
Audit
.
Example:
<MYSQL_VERSION>5.7.1-m11-log</MYSQL_VERSION>
<OS_LOGIN>
A string representing the external user name used during the
authentication process, as set by the plugin used to
authenticate the client. With native (built-in) MySQL
authentication, or if the plugin does not set the value,
this variable is NULL
. The value is the
same as that of the
external_user
system
variable. See Section 6.3.9, “Proxy Users”.
This element appears only if the
<NAME>
value is
Connect
, Change user
,
or Query
.
<OS_VERSION>
A string representing the operating system on which the
server was built or is running. This element appears only if
the <NAME>
value is
Audit
.
Example:
<OS_VERSION>x86_64-Linux</OS_VERSION>
<PRIV_USER>
A string representing the user that the server authenticated
the client as. This is the user name that the server uses
for privilege checking, and may differ from the
<USER>
value. This element appears
only if the <NAME>
value is
Connect
or Change
user
.
<PROXY_USER>
A string representing the proxy user. The value is empty if
user proxying is not in effect. This element appears only if
the <NAME>
value is
Connect
or Change
user
.
<SERVER_ID>
An unsigned integer representing the server ID. This is the
same as the value of the
server_id
system variable.
This element appears only if the
<NAME>
value is
Audit
or NoAudit
.
Example:
<SERVER_ID>1</SERVER_ID>
<SQLTEXT>
A string representing the text of an SQL statement. The
value can be empty. Long values may be truncated. This
element appears only if the <NAME>
value is Query
or
Execute
.
The string, like the audit log file itself, is written using UTF-8 (up to 4 bytes per character), so the value may be the result of conversion. For example, the original statement might have been received from the client as an SJIS string.
Example:
<SQLTEXT>DELETE FROM t1</SQLTEXT>
<STARTUP_OPTIONS>
A string representing the options that were given on the
command line or in option files when the MySQL server was
started. This element appears only if the
<NAME>
value is
Audit
.
Example:
<STARTUP_OPTIONS>/usr/local/mysql/bin/mysqld --port=3306 --log-output=FILE</STARTUP_OPTIONS>
<STATUS>
An unsigned integer representing the command status: 0 for
success, nonzero if an error occurred. This is the same as
the value of the
mysql_errno()
C API
function.
The audit log does not contain the SQLSTATE value or error message. To see the associations between error codes, SQLSTATE values, and messages, see Section B.3, “Server Error Codes and Messages”.
Warnings are not logged.
See the description for
<STATUS_CODE>
for information about
how it differs from <STATUS>
.
Example:
<STATUS>1051</STATUS>
<STATUS_CODE>
An unsigned integer representing the command status: 0 for success, 1 if an error occurred.
The STATUS_CODE
value differs from the
STATUS
value:
STATUS_CODE
is 0 for success and 1 for
error, which is compatible with the EZ_collector consumer
for Audit Vault. STATUS
is the value of
the mysql_errno()
C API
function. This is 0 for success and nonzero for error, and
thus is not necessarily 1 for error.
Example:
<STATUS_CODE>0</STATUS_CODE>
<USER>
A string representing the user name sent by the client. This
may differ from the <PRIV_USER>
value. This element appears only if the
<NAME>
value is
Connect
, Change user
,
or Query
.
Example:
<USER>root[root] @ localhost [127.0.0.1]</USER>
<VERSION>
An unsigned integer representing the version of the audit
log file format. This element appears only if the
<NAME>
value is
Audit
.
Example:
<VERSION>1</VERSION>
Every <AUDIT_RECORD>
element contains a
set of mandatory attributes. Other optional attributes may
appear depending on the audit record type.
The following attributes are mandatory in every
<AUDIT_RECORD>
element:
NAME
A string representing the type of instruction that generated the audit event, such as a command that the server received from a client.
Example: NAME="Query"
Some common NAME
values:
"Audit" When auditing starts, which may be server startup time "Connect" When a client connects, also known as logging in "Query" An SQL statement (executed directly) "Prepare" Preparation of an SQL statement; usually followed by Execute "Execute" Execution of an SQL statement; usually follows Prepare "Shutdown" Server shutdown "Quit" When a client disconnects "NoAudit" Auditing has been turned off
The possible values are "Audit"
,
"Binlog Dump"
, "Change
user"
, "Close stmt"
,
"Connect Out"
,
"Connect"
, "Create
DB"
, "Daemon"
,
"Debug"
, "Delayed
insert"
, "Drop DB"
,
"Execute"
, "Fetch"
,
"Field List"
, "Init
DB"
, "Kill"
, "Long
Data"
, "NoAudit"
,
"Ping"
, "Prepare"
,
"Processlist"
,
"Query"
, "Quit"
,
"Refresh"
, "Register
Slave"
, "Reset stmt"
,
"Set option"
,
"Shutdown"
, "Sleep"
,
"Statistics"
, "Table
Dump"
, "Time"
.
With the exception of "Audit"
and
"NoAudit"
, these values correspond to the
COM_
command values listed in the
xxx
mysql_com.h
header file. For example,
"Create DB"
and
"Shutdown"
correspond to
COM_CREATE_DB
and
COM_SHUTDOWN
, respectively.
TIMESTAMP
The date and time that the audit event was generated. For
example, the event corresponding to execution of an SQL
statement received from a client has a
TIMESTAMP
value occurring after the
statement finishes, not when it is received. The value is
UTC, in the format
(with yyyy-mm-dd
Thh:mm:ss
T
, no decimals).
Example: TIMESTAMP="2012-08-09T12:55:16"
The following attributes are optional in
<AUDIT_RECORD>
elements. Many of them
occur only for elements with specific values of the
NAME
attribute.
CONNECTION_ID
An unsigned integer representing the client connection
identifier. This is the same as the
CONNECTION_ID()
function
value within the session.
Example: CONNECTION_ID="127"
DB
A string representing the default database name. This
attribute appears only if the NAME
value
is "Connect"
or "Change
user"
.
HOST
A string representing the client host name. This attribute
appears only if the NAME
value is
"Connect"
or "Change
user"
.
Example: HOST="localhost"
IP
A string representing the client IP address. This attribute
appears only if the NAME
value is
"Connect"
or "Change
user"
.
Example: IP="127.0.0.1"
MYSQL_VERSION
A string representing the MySQL server version. This is the
same as the value of the
VERSION()
function or
version
system variable.
This attribute appears only if the NAME
value is "Audit"
.
Example: MYSQL_VERSION="5.7.11-log"
OS_LOGIN
A string representing the external user (empty if none). The
value may differ from USER
, for example,
if the server authenticates the client using an external
authentication method. This attribute appears only if the
NAME
value is
"Connect"
or "Change
user"
.
OS_VERSION
A string representing the operating system on which the
server was built or is running. This attribute appears only
if the NAME
value is
"Audit"
.
Example: OS_VERSION="x86_64-Linux"
PRIV_USER
A string representing the user that the server authenticated
the client as. This is the user name that the server uses
for privilege checking, and may be different from the
USER
value. This attribute appears only
if the NAME
value is
"Connect"
or "Change
user"
.
PROXY_USER
A string representing the proxy user. The value is empty if
user proxying is not in effect. This attribute appears only
if the NAME
value is
"Connect"
or "Change
user"
.
SERVER_ID
An unsigned integer representing the server ID. This is the
same as the value of the
server_id
system variable.
This attribute appears only if the NAME
value is "Audit"
or
"NoAudit"
.
Example: SERVER_ID="1"
SQLTEXT
A string representing the text of an SQL statement. The
value can be empty. Long values may be truncated. This
attribute appears only if the NAME
value
is "Query"
or
"Execute"
.
The string, like the audit log file itself, is written using UTF-8 (up to 4 bytes per character), so the value may be the result of conversion. For example, the original statement might have been received from the client as an SJIS string.
Example: SQLTEXT="DELETE FROM t1"
STARTUP_OPTIONS
A string representing the options that were given on the
command line or in option files when the MySQL server was
started. This attribute appears only if the
NAME
value is "Audit"
.
Example: STARTUP_OPTIONS="--port=3306
--log-output=FILE"
STATUS
An unsigned integer representing the command status: 0 for
success, nonzero if an error occurred. This is the same as
the value of the
mysql_errno()
C API
function.
The audit log does not contain the SQLSTATE value or error message. To see the associations between error codes, SQLSTATE values, and messages, see Section B.3, “Server Error Codes and Messages”.
Warnings are not logged.
Example: STATUS="1051"
USER
A string representing the user name sent by the client. This
may be different from the PRIV_USER
value. This attribute appears only if the
NAME
value is
"Connect"
or "Change
user"
.
VERSION
An unsigned integer representing the version of the audit
log file format. This attribute appears only if the
NAME
value is "Audit"
.
Example: VERSION="1"
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 6.4.4.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, you must 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 6.4.4.6, “Audit Log Plugin Options and Variables”.
To control the audit log file name, set the
audit_log_file
system variable
at server startup. By default, the name is
audit.log
in the server data directory. For
security reasons, the audit log file should be written to a
directory accessible only to the MySQL server and users with a
legitimate reason to view the log.
The audit log plugin can use any of several strategies for log
writes. To specify a strategy, set the
audit_log_strategy
system
variable at server startup. By default, the strategy value is
ASYNCHRONOUS
and the plugin logs
asynchronously to a buffer, waiting if the buffer is full. It's
possible to tell the plugin not to wait
(PERFORMANCE
) or to log synchronously, either
using file system caching (SEMISYNCHRONOUS
)
or forcing output with a sync()
call after
each write request (SYNCHRONOUS
).
Asynchronous logging strategy has these characteristics:
Minimal impact on server performance and scalability.
Blocking of threads that generate audit events for the shortest possible time; that is, time to allocate the buffer plus time to copy the event to the buffer.
Output goes to the buffer. A separate thread handles writes from the buffer to the log file.
A disadvantage of PERFORMANCE
strategy is
that it drops events when the buffer is full. For a heavily
loaded server, it is more likely that the audit log will be
missing events.
With asynchronous logging, the integrity of the log file may be
compromised if a problem occurs during a write to the file or if
the plugin does not shut down cleanly (for example, in the event
that the server host crashes). To reduce this risk, set
audit_log_strategy
to use
synchronous logging. Regardless of strategy, logging occurs on a
best-effort basis, with no guarantee of consistency.
The audit log plugin provides several system variables that enable you to manage the space used by its log files:
audit_log_buffer_size
: Set
this variable at server startup to set the size of the
buffer for asynchronous logging. The plugin uses a single
buffer, which it allocates when it initializes and removes
when it terminates. The plugin allocates this buffer only if
logging is asynchronous.
audit_log_rotate_on_size
,
audit_log_flush
: These
variables permit audit log file rotation and flushing. The
audit log file has the potential to grow very large and
consume a lot of disk space. To manage the space used,
either enable automatic log rotation, or manually rename the
audit file and flush the log to open a new file. The renamed
file can be removed or backed up as desired.
By default,
audit_log_rotate_on_size=0
and there is no log rotation. In this case, the audit log
plugin closes and reopens the log file when the
audit_log_flush
value
changes from disabled to enabled. Log file renaming must be
done externally to the server. Suppose that you want to
maintain the three most recent log files, which cycle
through the names audit.log.1.xml
through audit.log.3.xml
. On Unix,
perform rotation manually like this:
From the command line, rename the current log files:
shell>mv audit.log.2.xml audit.log.3.xml
shell>mv audit.log.1.xml audit.log.2.xml
shell>mv audit.log audit.log.1.xml
At this point, the plugin is still writing to the
current log file, which has been renamed to
audit.log.1.xml
.
Connect to the server and flush the log file so the
plugin closes it and reopens a new
audit.log
file:
mysql> SET GLOBAL audit_log_flush = ON;
If audit_log_rotate_on_size
is greater than 0, setting
audit_log_flush
has no
effect. In this case, the audit log plugin closes and
reopens its log file whenever a write to the file causes its
size to exceed the
audit_log_rotate_on_size
value. The plugin renames the original file to have an
extension consisting of a timestamp and
.xml
suffix. For example,
audit.log
might be renamed to
audit.log.13792588477726520.xml
. The
last 7 digits of the timestamp are a fractional second part.
The first 10 digits are a Unix timestamp value that can be
interpreted using the
FROM_UNIXTIME()
function:
mysql> SELECT FROM_UNIXTIME(1379258847);
+---------------------------+
| FROM_UNIXTIME(1379258847) |
+---------------------------+
| 2013-09-15 10:27:27 |
+---------------------------+
The audit log plugin can filter audited events. This enables you to control whether it writes events to the audit log file based on the account from which events originate or event status. Status filtering occurs separately for connection events and statement events.
To filter audited events based on the originating account, set one of these system variables at server startup or runtime:
audit_log_include_accounts
:
The accounts to include in audit logging. If this variable
is set, only these accounts are audited.
audit_log_exclude_accounts
:
The accounts to exclude from audit logging. If this variable
is set, all but these accounts are audited.
The value for either variable can be NULL
or
a string containing one or more comma-separated account names,
each in
format. By default, both variables are user_name
@host_name
NULL
,
in which case, no account filtering is done and auditing occurs
for all accounts.
Modifications to
audit_log_include_accounts
or
audit_log_exclude_accounts
affect only connections created subsequent to the modification,
not existing connections.
Example: To enable audit logging only for the
user1
and user2
local host
account accounts, set the
audit_log_include_accounts
system variable like this:
SET GLOBAL audit_log_include_accounts = 'user1@localhost,user2@localhost';
Only one of
audit_log_include_accounts
or
audit_log_exclude_accounts
can
be non-NULL
at a time:
If you set
audit_log_include_accounts
,
the server sets
audit_log_exclude_accounts
to NULL
.
If you attempt to set
audit_log_exclude_accounts
,
an error occurs unless
audit_log_include_accounts
is NULL
. In this case, you must first
clear
audit_log_include_accounts
by setting it to NULL
.
-- This sets audit_log_exclude_accounts to NULL SET GLOBAL audit_log_include_accounts =value
; -- This fails because audit_log_include_accounts is not NULL SET GLOBAL audit_log_exclude_accounts =value
; -- To set audit_log_exclude_accounts, first set -- audit_log_include_accounts to NULL SET GLOBAL audit_log_include_accounts = NULL; SET GLOBAL audit_log_exclude_accounts =value
;
If you inspect the value of either variable, be aware that
SHOW VARIABLES
displays
NULL
as an empty string. To avoid this, use
SELECT
instead:
mysql>SHOW VARIABLES LIKE 'audit_log_include_accounts';
+----------------------------+-------+ | Variable_name | Value | +----------------------------+-------+ | audit_log_include_accounts | | +----------------------------+-------+ mysql>SELECT @@audit_log_include_accounts;
+------------------------------+ | @@audit_log_include_accounts | +------------------------------+ | NULL | +------------------------------+
If a user name or host name requires quoting because it contains
a comma, space, or other special character, quote it using
single quotes. If the variable value itself is quoted with
single quotes, double each inner single quote or escape it with
a backslash. The following statements each enable audit logging
for the local root
account and are
equivalent, even though the quoting styles differ:
SET GLOBAL audit_log_include_accounts = 'root@localhost'; SET GLOBAL audit_log_include_accounts = '''root''@''localhost'''; SET GLOBAL audit_log_include_accounts = '\'root\'@\'localhost\''; SET GLOBAL audit_log_include_accounts = "'root'@'localhost'";
The last statement will not work if the
ANSI_QUOTES
SQL mode is enabled because in
that mode double quotes signify identifier quoting, not string
quoting.
To filter audited events based on status, set these system variables at server startup or runtime:
audit_log_connection_policy
:
Logging policy for connection events
audit_log_statement_policy
:
Logging policy for statement events
Each variable takes a value of ALL
(log all
associated events; this is the default),
ERRORS
(log only failed events), or
NONE
(do not log events). For example, to log
all statement events but only failed connection events, use
these settings:
SET GLOBAL audit_log_statement_policy = ALL; SET GLOBAL audit_log_connection_policy = ERRORS;
Another policy system variable,
audit_log_policy
, is available
but does not afford as much control as
audit_log_connection_policy
and
audit_log_statement_policy
. It
can be set only at server startup. At runtime, it is a read-only
variable. It takes a value of ALL
(log all
events; this is the default), LOGINS
(log
connection events), QUERIES
(log statement
events), or NONE
(do not log events). For any
of those values, the audit log plugin logs all selected events
without distinction as to success or failure. Use of
audit_log_policy
at startup
works as follows:
If you do not set
audit_log_policy
or set it
to its default of ALL
, any explicit
settings for
audit_log_connection_policy
or
audit_log_statement_policy
apply as specified. If not specified, they default to
ALL
.
If you set audit_log_policy
to a non-ALL
value, that value takes
precedence over and is used to set
audit_log_connection_policy
and
audit_log_statement_policy
,
as indicated in the following table. If you also set either
of those variables to a value other than their default of
ALL
, the server writes a message to the
error log to indicate that their values are being
overridden.
Startup audit_log_policy Value | Resulting audit_log_connection_policy Value | Resulting audit_log_statement_policy Value |
---|---|---|
LOGINS | ALL | NONE |
QUERIES | NONE | ALL |
NONE | NONE | NONE |
To check the effect of filtering, you can inspect the values of these status variables:
Audit_log_events
: The number of events
handled by the audit log plugin, whether or not they were
written to the log based on filtering policy.
Audit_log_events_filtered
: The number of
events handled by the audit log plugin that were filtered
(not written to the log) based on filtering policy.
Audit_log_events_written
: The number of
events written to the audit log.
Table 6.18 Audit Log Plugin Option/Variable Reference
Name | Cmd-Line | Option File | System Var | Status Var | Var Scope | Dynamic |
---|---|---|---|---|---|---|
audit-log | Yes | Yes | ||||
audit_log_buffer_size | Yes | Yes | Yes | Global | No | |
audit_log_connection_policy | Yes | Yes | Yes | Global | Yes | |
audit_log_current_session | Yes | Both | No | |||
Audit_log_current_size | Yes | Global | No | |||
Audit_log_event_max_drop_size | Yes | Global | No | |||
Audit_log_events | Yes | Global | No | |||
Audit_log_events_filtered | Yes | Global | No | |||
Audit_log_events_lost | Yes | Global | No | |||
Audit_log_events_written | Yes | Global | No | |||
audit_log_exclude_accounts | Yes | Yes | Yes | Global | Yes | |
audit_log_file | Yes | Yes | Yes | Global | No | |
audit_log_flush | Yes | Global | Yes | |||
audit_log_format | Yes | Yes | Yes | Global | No | |
audit_log_include_accounts | Yes | Yes | Yes | Global | Yes | |
audit_log_policy | Yes | Yes | Yes | Global | No | |
audit_log_rotate_on_size | Yes | Yes | Yes | Global | Yes | |
audit_log_statement_policy | Yes | Yes | Yes | Global | Yes | |
audit_log_strategy | Yes | Yes | Yes | Global | No | |
Audit_log_total_size | Yes | Global | No | |||
Audit_log_write_waits | Yes | Global | No |
This section describes the command options and system variables that control operation of the audit log plugin. If values specified at startup time are incorrect, the 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:
Introduced | 5.7.9 | ||
Command-Line Format | --audit-log[=value] | ||
Permitted Values | Type | enumeration | |
Default | ON | ||
Valid Values | ON | ||
OFF | |||
FORCE | |||
FORCE_PLUS_PERMANENT |
This option controls how the server loads the
audit_log
plugin at startup. It is
available only if the audit log plugin has been previously
registered with INSTALL
PLUGIN
or is loaded with
--plugin-load
. See
Section 6.4.4.1, “Installing the Audit Log Plugin”.
The option value should be one of those available for
plugin-loading options, as described in
Section 5.1.8.1, “Installing and Uninstalling Plugins”. For example,
--audit-log=FORCE_PLUS_PERMANENT
tells the server to load the plugin and prevent it from
being removed while the server is running.
If the audit_log
plugin is installed, it
exposes several system variables that permit control over
logging: These variables are available only if the
audit_log
plugin is enabled.
mysql> SHOW VARIABLES LIKE 'audit_log%';
+-----------------------------+--------------+
| Variable_name | Value |
+-----------------------------+--------------+
| audit_log_buffer_size | 1048576 |
| audit_log_connection_policy | ALL |
| audit_log_current_session | ON |
| audit_log_exclude_accounts | |
| audit_log_file | audit.log |
| audit_log_flush | OFF |
| audit_log_format | NEW |
| audit_log_include_accounts | |
| audit_log_policy | ALL |
| audit_log_rotate_on_size | 0 |
| audit_log_statement_policy | ALL |
| audit_log_strategy | ASYNCHRONOUS |
+-----------------------------+--------------+
You can set any of these variables at server startup, and some of them at runtime.
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_buffer_size=value | ||
System Variable | Name | audit_log_buffer_size | |
Variable Scope | Global | ||
Dynamic Variable | No | ||
Permitted Values (32-bit platforms) | Type | integer | |
Default | 1048576 | ||
Min Value | 4096 | ||
Max Value | 4294967295 | ||
Permitted Values (64-bit platforms) | Type | integer | |
Default | 1048576 | ||
Min Value | 4096 | ||
Max Value | 18446744073709547520 |
When the audit log plugin writes events to the log asynchronously, it uses a buffer to store event contents prior to writing them. This variable controls the size of that buffer, in bytes. The server adjusts the value to a multiple of 4096. The plugin uses a single buffer, which it allocates when it initializes and removes when it terminates. The plugin allocates this buffer only if logging is asynchronous.
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_connection_policy=value | ||
System Variable | Name | audit_log_connection_policy | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | enumeration | |
Default | ALL | ||
Valid Values | ALL | ||
ERRORS | |||
NONE |
The policy controlling how the audit log plugin writes connection events to its log file. The following table shows the permitted values.
Value | Description |
---|---|
ALL | Log all connection events |
ERRORS | Log only failed connection events |
NONE | Do not log connection events |
At server startup, any explicit value given for
audit_log_connection_policy
may be overridden if
audit_log_policy
is also
specified, as described in
Section 6.4.4.4, “Audit Log Plugin Logging Control”.
Introduced | 5.7.9 | ||
System Variable | Name | audit_log_current_session | |
Variable Scope | Global, Session | ||
Dynamic Variable | No | ||
Permitted Values | Type | boolean | |
Default | depends on filtering policy |
Whether audit logging is enabled for the current session.
The session value of this variable is read only. It is set
when the session begins based on the values of the
audit_log_include_accounts
and
audit_log_exclude_accounts
system variables. The audit log plugin uses the session
value to determine whether to audit events for the session.
(There is a global value, but the plugin does not use it.)
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_exclude_accounts=value | ||
System Variable | Name | audit_log_exclude_accounts | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | string | |
Default | NULL |
The accounts for which events should not be logged. The
value should be NULL
or a string
containing a list of one or more comma-separated account
names. For more information, see
Section 6.4.4.4, “Audit Log Plugin Logging Control”.
Modifications to
audit_log_exclude_accounts
affect only connections created subsequent to the
modification, not existing connections.
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_file=file_name | ||
System Variable | Name | audit_log_file | |
Variable Scope | Global | ||
Dynamic Variable | No | ||
Permitted Values | Type | file name | |
Default | audit.log |
The name of the file to which the audit log plugin writes
events. The default value is audit.log
.
If the file name is a relative path, the server interprets
it relative to the data directory. For security reasons, the
audit log file should be written to a directory accessible
only to the MySQL server and users with a legitimate reason
to view the log.
Introduced | 5.7.9 | ||
System Variable | Name | audit_log_flush | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | boolean | |
Default | OFF |
When this variable is set to enabled (1 or
ON
), the audit log plugin closes and
reopens its log file to flush it. (The value remains
OFF
so that you need not disable it
explicitly before enabling it again to perform another
flush.) Enabling this variable has no effect unless
audit_log_rotate_on_size
is
0.
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_format=value | ||
System Variable | Name | audit_log_format | |
Variable Scope | Global | ||
Dynamic Variable | No | ||
Permitted Values (>= 5.7.9) | Type | enumeration | |
Default | NEW | ||
Valid Values | OLD | ||
NEW |
The audit log file format. Permitted values are
OLD
and NEW
(default
NEW
). For details about each format, see
Section 6.4.4.3, “The Audit Log File”.
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:
Stop the server.
Rename the current audit log file manually.
Restart the server with the new value of
audit_log_format
. The
audit log plugin will create a new log file, which will
contain log entries in the selected format.
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_include_accounts=value | ||
System Variable | Name | audit_log_include_accounts | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | string | |
Default | NULL |
The accounts for which events should be logged. The value
should be NULL
or a string containing a
list of one or more comma-separated account names. For more
information, see
Section 6.4.4.4, “Audit Log Plugin Logging Control”.
Modifications to
audit_log_include_accounts
affect only connections created subsequent to the
modification, not existing connections.
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_policy=value | ||
System Variable | Name | audit_log_policy | |
Variable Scope | Global | ||
Dynamic Variable | No | ||
Permitted Values | Type | enumeration | |
Default | ALL | ||
Valid Values | ALL | ||
LOGINS | |||
QUERIES | |||
NONE |
The policy controlling how the audit log plugin writes events to its log file. The following table shows the permitted values.
Value | Description |
---|---|
ALL | Log all events |
LOGINS | Log only login events |
QUERIES | Log only query events |
NONE | Log nothing (disable the audit stream) |
audit_log_policy
can be set
only at server startup. At runtime, it is a read-only
variable. Two other system variables,
audit_log_connection_policy
and
audit_log_statement_policy
,
provide finer control over logging policy and can be set
either at startup or at runtime. If you use
audit_log_policy
at startup
instead of the other two variables, the server uses its
value to set those variables. For more information about the
policy variables and their interaction, see
Section 6.4.4.4, “Audit Log Plugin Logging Control”.
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_rotate_on_size=N | ||
System Variable | Name | audit_log_rotate_on_size | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | integer | |
Default | 0 |
If the
audit_log_rotate_on_size
value is greater than 0, the audit log plugin closes and
reopens its log file if a write to the file causes its size
to exceed this value. The original file is renamed to have a
timestamp extension.
If the
audit_log_rotate_on_size
value is 0, the plugin does not close and reopen its log
based on size. Instead, use
audit_log_flush
to close
and reopen the log on demand. In this case, rename the file
externally to the server before flushing it.
For more information about audit log file rotation and timestamp interpretation, see Section 6.4.4.4, “Audit Log Plugin Logging Control”.
If you set this variable to a value that is not a multiple of 4096, it is truncated to the nearest multiple. (Thus, setting it to a value less than 4096 has the effect of setting it to 0 and no rotation occurs.)
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_statement_policy=value | ||
System Variable | Name | audit_log_statement_policy | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | enumeration | |
Default | ALL | ||
Valid Values | ALL | ||
ERRORS | |||
NONE |
The policy controlling how the audit log plugin writes statement events to its log file. The following table shows the permitted values.
Value | Description |
---|---|
ALL | Log all statement events |
ERRORS | Log only failed statement events |
NONE | Do not log statement events |
At server startup, any explicit value given for
audit_log_statement_policy
may be overridden if
audit_log_policy
is also
specified, as described in
Section 6.4.4.4, “Audit Log Plugin Logging Control”.
Introduced | 5.7.9 | ||
Command-Line Format | --audit_log_strategy=value | ||
System Variable | Name | audit_log_strategy | |
Variable Scope | Global | ||
Dynamic Variable | No | ||
Permitted Values | Type | enumeration | |
Default | ASYNCHRONOUS | ||
Valid Values | ASYNCHRONOUS | ||
PERFORMANCE | |||
SEMISYNCHRONOUS | |||
SYNCHRONOUS |
The logging method used by the audit log plugin. The following table describes the permitted values.
Table 6.19 Audit Log Strategies
Value | Meaning |
---|---|
ASYNCHRONOUS | Log asynchronously, wait for space in output buffer |
PERFORMANCE | Log asynchronously, drop request if insufficient space in output buffer |
SEMISYNCHRONOUS | Log synchronously, permit caching by operating system |
SYNCHRONOUS | Log synchronously, call sync() after each request |
The audit log plugin supports the following status variables.
They are available only if the audit_log
plugin is enabled.
The size of the current audit log file. The value increases when an event is written to the log and is reset to 0 when the log is rotated.
The size of the largest dropped event in performance logging mode. For a description of logging modes, see Section 6.4.4.4, “Audit Log Plugin Logging Control”.
The number of events handled by the audit log plugin, whether or not they were written to the log based on filtering policy (see Section 6.4.4.4, “Audit Log Plugin Logging Control”).
The number of events handled by the audit log plugin that were filtered (not written to the log) based on filtering policy (see Section 6.4.4.4, “Audit Log Plugin Logging Control”).
The number of events lost in performance logging mode
because an event was larger than than the available audit
log buffer space. This value may be useful for assessing how
to set
audit_log_buffer_size
to
size the buffer for performance mode. For a description of
logging modes, see
Section 6.4.4.4, “Audit Log Plugin Logging Control”.
The number of events written to the audit log.
The total size of events written to all audit log files.
Unlike
Audit_log_current_size
,
the value of
Audit_log_total_size
increases even when the log is rotated.
The number of times an event had to wait for space in the audit log buffer in asynchronous logging mode. For a description of logging modes, see Section 6.4.4.4, “Audit Log Plugin Logging Control”.
The audit log plugin is subject to these general restrictions:
Only SQL statements are logged. Changes made by no-SQL APIs, such as memcached, Node.JS, and the NDB API, are not logged.
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.
MySQL Cluster. It is possible to use the audit log plugin with MySQL Cluster, subject to the following conditions:
All changes to be logged must be done using the SQL interface. Changes using no-SQL interfaces, such as those provided by the NDB API, memcached, or ClusterJ, are not logged.
The plugin must be installed on each MySQL server that is used to execute SQL on the cluster.
Audit plugin data must be aggregated amongst all MySQL servers used with the cluster. This aggregation is the responsibility of the application or user.
MySQL Enterprise Firewall is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see http://www.mysql.com/products/.
As of MySQL 5.7.9, MySQL Enterprise Edition includes MySQL Enterprise Firewall, an application-level firewall that enables database administrators to permit or deny SQL statement execution based on matching against whitelists of accepted statement patterns. This helps harden MySQL Server against attacks such as SQL injection or attempts to exploit applications by using them outside of their legitimate query workload characteristics.
Each MySQL account registered with the firewall has its own statement whitelist, enabling protection to be tailored per account. For a given account, the firewall can operate in recording, protecting, or detecting mode, for training in the accepted statement patterns, active protection against unacceptable statements, or passive detection of unacceptable statements. The diagram illustrates how the firewall processes incoming statements in each mode.
The following sections describe the components of MySQL Enterprise Firewall, discuss how to install and use it, and provide reference information for its components.
MySQL Enterprise Firewall is based on a plugin library that implements these components:
A server-side plugin named MYSQL_FIREWALL
examines SQL statements before they execute and, based on
its in-memory cache, renders a decision whether to execute
or reject each statement.
Server-side plugins named
MYSQL_FIREWALL_USERS
and
MYSQL_FIREWALL_WHITELIST
implement
INFORMATION_SCHEMA
tables that provide
views into the firewall data cache.
System tables named firewall_users
and
firewall_whitelist
in the
mysql
database provide persistent storage
of firewall data.
Stored procedures named
sp_set_firewall_mode()
and
sp_reload_firewall_rules()
perform tasks
such as registering MySQL accounts with the firewall,
establishing their operational mode, and managing transfer
of firewall data between the cache and the underlying system
tables.
A set of user-defined functions provides an SQL-level API for lower-level tasks such as synchronizing the cache with the underlying system tables.
System variables enable firewall configuration and status variables provide runtime operational information.
MySQL Enterprise Firewall installation is a one-time operation that installs the components described in Section 6.4.5.1, “MySQL Enterprise Firewall Components”. Installation can be performed using a graphical interface or manually:
On Windows, MySQL Installer includes an option to enable MySQL Enterprise Firewall for you.
MySQL Workbench 6.3.4 or higher can install MySQL Enterprise Firewall, enable or disable an installed firewall, or uninstall the firewall.
Manual MySQL Enterprise Firewall installation involves running a script located
in the share
directory of your MySQL
installation.
If installed, MySQL Enterprise Firewall involves some minimal overhead even when disabled. To avoid this overhead, do not install the firewall unless you plan to use it.
MySQL Enterprise Firewall does not work together with the query cache. If the query cache is enabled, disable it before installing the firewall (see Section 8.10.3.3, “Query Cache Configuration”).
For usage instructions, see Section 6.4.5.3, “Using MySQL Enterprise Firewall”. For reference information, see Section 6.4.5.4, “MySQL Enterprise Firewall Reference”.
If MySQL Enterprise Firewall is already installed from an older version version of MySQL, uninstall it using the instructions given later in this section before installing the current version. In this case, it is also necessary to register your configuration again.
On Windows, you can use MySQL Installer to install MySQL Enterprise Firewall, as shown in Figure 6.2, “MySQL Enterprise Firewall Installation on Windows”. Check the Enable Enterprise Firewall checkbox. (Open Firewall port for network access has a different purpose. It refers to Windows Firewall and controls whether Windows blocks the TCP/IP port on which the MySQL server listens for client connections.)
To install MySQL Enterprise Firewall using MySQL Workbench 6.3.4 or higher, see MySQL Enterprise Firewall Interface.
To install MySQL Enterprise Firewall manually, look in the
share
directory of your MySQL
installation and choose the script that is appropriate for
your platform. The available scripts differ in the suffix used
to refer to the plugin library file:
win_install_firewall.sql
: Choose this
script for Windows systems that use
.dll
as the file name suffix.
linux_install_firewall.sql
: Choose
this script for Linux and similar systems that use
.so
as the file name suffix.
The installation script creates stored procedures in the
default database, so choose a database to use. Then run the
script as follows, naming the chosen database on the command
line. The example here uses the mysql
database and the Linux installation script. Make the
appropriate substitutions for your system.
shell>mysql -u root -p mysql < linux_install_firewall.sql
Enter password:(enter root password here)
Installing MySQL Enterprise Firewall either using a graphical interface or manually should enable the firewall. To verify that, connect to the server and execute this statement:
mysql> SHOW GLOBAL VARIABLES LIKE 'mysql_firewall_mode';
+---------------------+-------+
| Variable_name | Value |
+---------------------+-------+
| mysql_firewall_mode | ON |
+---------------------+-------+
MySQL Enterprise Firewall can be uninstalled using MySQL Workbench or manually.
To uninstall MySQL Enterprise Firewall using MySQL Workbench 6.3.4 or higher, see MySQL Enterprise Firewall Interface.
To uninstall MySQL Enterprise Firewall manually, execute the following
statements. It is assumed that the stored procedures were
created in the mysql
database. Adjust the
DROP PROCEDURE
statements
appropriately if the procedures were created in a different
database.
DROP TABLE mysql.firewall_whitelist; DROP TABLE mysql.firewall_users; UNINSTALL PLUGIN mysql_firewall; UNINSTALL PLUGIN mysql_firewall_whitelist; UNINSTALL PLUGIN mysql_firewall_users; DROP FUNCTION set_firewall_mode; DROP FUNCTION normalize_statement; DROP FUNCTION read_firewall_whitelist; DROP FUNCTION read_firewall_users; DROP FUNCTION mysql_firewall_flush_status; DROP PROCEDURE mysql.sp_set_firewall_mode; DROP PROCEDURE mysql.sp_reload_firewall_rules;
Before using MySQL Enterprise Firewall, install it according to the instructions at Section 6.4.5.2, “Installing or Uninstalling MySQL Enterprise Firewall”. Also, MySQL Enterprise Firewall does not work together with the query cache; disable the query cache if it is enabled (see Section 8.10.3.3, “Query Cache Configuration”).
This section describes how to configure MySQL Enterprise Firewall using SQL statements. Alternatively, MySQL Workbench 6.3.4 or higher provides a graphical interface for firewall control. See MySQL Enterprise Firewall Interface.
To enable or disable the firewall, set the
mysql_firewall_mode
system
variable. By default, this variable is enabled when the firewall
is installed. To control the initial firewall state explicitly,
you can set the variable at server startup. For example, to
enable the firewall in an option file, use these lines:
[mysqld] mysql_firewall_mode=ON
It is also possible to disable or enable the firewall at runtime:
mysql>SET GLOBAL mysql_firewall_mode = OFF;
mysql>SET GLOBAL mysql_firewall_mode = ON;
In addition to the global on/off firewall mode, each account registered with the firewall has its own operational mode. For an account in recording mode, the firewall learns an application's “fingerprint,” that is, the acceptable statement patterns that, taken together, form a whitelist. After training, switch the firewall to protecting mode to harden MySQL against access by statements that deviate from the fingerprint. For additional training, switch the firewall back to recording mode as necessary to update the whitelist with new statement patterns. An intrusion-detection mode is available that writes suspicious statements to the error log but does not deny access.
The firewall maintains whitelist rules on a per-account basis, enabling implementation of protection strategies such as these:
For an application that has unique protection requirements, configure it to use an account that is not used for any other purpose.
For applications that are related and share protection requirements, configure them as a group to use the same account.
Firewall operation is based on conversion of SQL statements to
normalized digest form. Firewall digests are like the statement
digests used by the Performance Schema (see
Section 22.7, “Performance Schema Statement Digests”).
However, unlike the Performance Schema, the relevant
digest-related system variable is
max_digest_length
.
For a connection from a registered account, the firewall converts each incoming statement to normalized form and processes it according to the account mode:
In recording mode, the firewall adds the normalized statement to the account whitelist rules.
In protecting mode, the firewall compares the normalized
statement to the account whitelist rules. If there is a
match, the statement passes and the server continues to
process it. Otherwise, the server rejects the statement and
returns an error to the client. The firewall also writes the
rejected statement to the error log if the
mysql_firewall_trace
system
variable is enabled.
In detecting mode, the firewall matches statements as in protecting mode, but writes nonmatching statements to the error log without denying access.
Accounts that have a mode of OFF
or are not
registered with the firewall are ignored by it.
To protect an account using MySQL Enterprise Firewall, follow these steps:
Register the account and put it in recording mode.
Connect to the MySQL server using the registered account and execute statements to be learned. This establishes the account's whitelist of accepted statements.
Switch the registered account to protecting mode.
The following example shows how to register an account with the
firewall, use the firewall to learn acceptable statements for
that account, and protect the account against execution of
unacceptable statements. The example account,
'fwuser'@'localhost'
, is for use by an
application that accesses tables in the
sakila
database. (This database is available
at http://dev.mysql.com/doc/index-other.html.)
The user and host parts of the account name are quoted
separately for statements such as CREATE
USER
and GRANT
,
whereas to specify an account for use with a firewall
component, name it as a single quoted string
'fwuser@localhost'
.
The convention for naming accounts as a single quoted string
for firewall components means that you cannot use accounts
that have embedded @
characters in the user
name.
Perform the steps in the following procedure using an
administrative MySQL account, except those designated for
execution by the account registered with the firewall. The
default database should be sakila
for
statements executed using the registered account.
If necessary, create the account to be protected (choose an
appropriate password) and grant it privileges for the
sakila
database:
mysql>CREATE USER 'fwuser'@'localhost' IDENTIFIED BY 'fWp@3sw0rd';
mysql>GRANT ALL ON sakila.* TO 'fwuser'@'localhost';
Use the sp_set_firewall_mode()
stored
procedure to register the account with the firewall and
place it in recording mode (if the procedure is located in a
database other than mysql
, adjust the
statement accordingly):
mysql> CALL mysql.sp_set_firewall_mode('fwuser@localhost', 'RECORDING');
During the course of its execution, the stored procedure invokes firewall user-defined functions, which may produce output of their own.
Using the registered account, connect to the server, then execute some statements that are legitimate for it:
mysql>SELECT first_name, last_name FROM customer WHERE customer_id = 1;
mysql>UPDATE rental SET return_date = NOW() WHERE rental_id = 1;
mysql>SELECT get_customer_balance(1, NOW());
The firewall converts the statements to digest form and records them in the account whitelist.
Until the account executes statements in recording mode, its whitelist is empty, which is equivalent to “deny all.” If switched to protecting mode, the account will be effectively prohibited from executing statements.
At this point, the user and whitelist information is cached
and can be seen in the firewall
INFORMATION_SCHEMA
tables:
mysql>SELECT MODE FROM INFORMATION_SCHEMA.MYSQL_FIREWALL_USERS
->WHERE USERHOST = 'fwuser@localhost';
+-----------+ | MODE | +-----------+ | RECORDING | +-----------+ mysql>SELECT RULE FROM INFORMATION_SCHEMA.MYSQL_FIREWALL_WHITELIST
->WHERE USERHOST = 'fwuser@localhost';
+----------------------------------------------------------------------------+ | RULE | +----------------------------------------------------------------------------+ | SELECT `first_name` , `last_name` FROM `customer` WHERE `customer_id` = ? | | SELECT `get_customer_balance` ( ? , NOW ( ) ) | | UPDATE `rental` SET `return_date` = NOW ( ) WHERE `rental_id` = ? | | SELECT @@`version_comment` LIMIT ? | +----------------------------------------------------------------------------+
The @@version_comment
rule comes from a
statement sent automatically by the
mysql client when you connect to the
server as the registered user.
It is important to train the firewall under conditions matching application use. For example, a given MySQL connector might send statements to the server at the beginning of a connection to determine server characteristics and capabilities. If an application normally is used through that connector, train the firewall that way, too. That enables those initial statements to become part of the whitelist for the account associated with the application.
Use the stored procedure to switch the registered user to protecting mode:
mysql> CALL mysql.sp_set_firewall_mode('fwuser@localhost', 'PROTECTING');
Switching the account out of RECORDING
mode synchronizes its firewall cache data to the
underlying mysql
system database tables
for persistent storage. If you do not switch the mode for
a user who is being recorded, the cached whitelist data is
not written to the system tables and will be lost when the
server is restarted.
Using the registered account, execute some acceptable and unacceptable statements. The firewall matches each one against the account whitelist and accepts or rejects it.
This statement is not identical to a training statement but produces the same normalized statement as one of them, so the firewall accepts it:
mysql> SELECT first_name, last_name FROM customer WHERE customer_id = '48';
+------------+-----------+
| first_name | last_name |
+------------+-----------+
| ANN | EVANS |
+------------+-----------+
These statements do not match anything in the whitelist and each results in an error:
mysql>SELECT first_name, last_name FROM customer WHERE customer_id = 1 OR TRUE;
ERROR 1045 (28000): Statement was blocked by Firewall mysql>SHOW TABLES LIKE 'customer%';
ERROR 1045 (28000): Statement was blocked by Firewall mysql>TRUNCATE TABLE mysql.slow_log;
ERROR 1045 (28000): Statement was blocked by Firewall
The firewall also writes the rejected statements to the
error log if the
mysql_firewall_trace
system
variable is enabled. For example:
[Note] Plugin MYSQL_FIREWALL reported: 'ACCESS DENIED for fwuser@localhost. Reason: No match in whitelist. Statement: TRUNCATE TABLE `mysql` . `slow_log` '
You can use these log messages in your efforts to identify the source of attacks.
You can log nonmatching statements as suspicious without denying access. To do this, put the account in intrusion-detecting mode:
mysql> CALL mysql.sp_set_firewall_mode('fwuser@localhost', 'DETECTING');
Using the registered account, connect to the server, then execute some statement does not match the whitelist:
mysql> SHOW TABLES LIKE 'customer%';
+------------------------------+
| Tables_in_sakila (customer%) |
+------------------------------+
| customer |
| customer_list |
+------------------------------+
In detecting mode, the firewall permits the nonmatching statement to execute but writes a message to the error log:
[Note] Plugin MYSQL_FIREWALL reported: 'SUSPICIOUS STATEMENT from 'fwuser@localhost'. Reason: No match in whitelist. Statement: SHOW TABLES LIKE ? '
To assess firewall activity, examine its status variables:
mysql> SHOW GLOBAL STATUS LIKE 'Firewall%';
+----------------------------+-------+
| Variable_name | Value |
+----------------------------+-------+
| Firewall_access_denied | 3 |
| Firewall_access_granted | 4 |
| Firewall_access_suspicious | 1 |
| Firewall_cached_entries | 4 |
+----------------------------+-------+
The variables indicate the number of statements rejected,
accepted, logged as suspicious, and added to the cache,
respectively. The
Firewall_access_granted
count is 4 because of the
@@version_comment
statement sent by the
mysql client each of the three time you
used it to connect as the registered user, plus the
SHOW TABLES
statement that
was not blocked in DETECTING
mode.
Should additional training for an account be necessary, switch it to recording mode again, then back to protecting mode after executing statements to be added to the whitelist.
The following discussion serves as a reference to these MySQL Enterprise Firewall components:
Firewall tables in the mysql
and
INFORMATION_SCHEMA
databases
Firewall procedures and functions
Firewall system and status variables
MySQL Enterprise Firewall maintains account and whitelist information. It uses
INFORMATION_SCHEMA
tables to provide views
into cached data, and tables in the mysql
system database to store this data in persistent form. When
enabled, the firewall bases its operational decisions on the
cached data.
The INFORMATION_SCHEMA
tables are
accessible by anyone. The mysql
tables can
be accessed only by users with privileges for that database.
The INFORMATION_SCHEMA.MYSQL_FIREWALL_USERS
and mysql.firewall_users
tables list
registered firewall accounts and their operational modes. The
tables have these columns:
USERHOST
An account registered with the firewall. Each account has
the format
and represents actual user and host names as authenticated
by the server. Patterns and netmasks should not be used
when registering users.
user_name
@host_name
MODE
The current firewall operational mode for the account. The
permitted mode values are OFF
,
DETECTING
,
PROTECTING
,
RECORDING
, and
RESET
. For details about their
meanings, see the description of
sp_set_firewall_mode()
in
Section 6.4.5.4.2, “MySQL Enterprise Firewall Procedures and Functions”.
The
INFORMATION_SCHEMA.MYSQL_FIREWALL_WHITELIST
and mysql.firewall_whitelist
tables list
registered firewall accounts and their whitelists. The tables
have these columns:
USERHOST
An account registered with the firewall. The format is the same as for the user account tables.
RULE
A normalized statement indicating an acceptable statement pattern for the account. An account whitelist is the union of its rules.
MySQL Enterprise Firewall has stored procedures that perform tasks such as registering MySQL accounts with the firewall, establishing their operational mode, and managing transfer of firewall data between the cache and the underlying system tables. It also has a set of user-defined functions (UDFs) that provides an SQL-level API for lower-level tasks such as synchronizing the cache with the underlying system tables.
Under normal operation, the stored procedures implement the user interface. The UDFs are invoked by the stored procedures, not directly by users.
To invoke a stored procedure when the default database is not the database that contains the procedure, qualify the procedure name with the database name. For example:
CALL mysql.sp_set_firewall_mode(user
,mode
);
The following list describes each firewall stored procedure and UDF:
sp_reload_firewall_rules(
user
)
This stored procedure uses firewall UDFs to reset a
registered account and reload the in-memory rules for it
from the rules stored in the
mysql.firewall_whitelist
table. This
procedure provides control over firewall operation for
individual accounts.
The user
argument names the
affected account, as a string in
format.
user_name
@host_name
Example:
CALL mysql.sp_reload_firewall_rules('fwuser@localhost');
This procedure sets the account mode to
RESET
, which clears the account
whitelist and sets its mode to OFF
.
If the account mode was not OFF
prior
to the sp_reload_firewall_rules()
call, use sp_set_firewall_mode()
to
restore its previous mode after reloading the rules. For
example, if the account was in
PROTECTING
mode, that is no longer
true after calling
sp_reload_firewall_rules()
and you
must set it to PROTECTING
again
explicitly.
sp_set_firewall_mode(
user
,
mode
)
This stored procedure registers a MySQL account with the
firewall and establishes its operational mode. The
procedure also invokes firewall UDFs as necessary to
transfer firewall data between the cache and the
underlying system tables. This procedure may be called
even if the mysql_firewall_mode
system
variable is OFF
, although setting the
mode for an account has no operational effect while the
firewall is disabled.
The user
argument names the
affected account, as a string in
format.
user_name
@host_name
The mode
is the operational
mode for the user, as a string. These mode values are
permitted:
OFF
: Disable the firewall for the
account.
DETECTING
: Intrusion-detection
mode: Write suspicious (nonmatching) statements to the
error log but do not deny access.
PROTECTING
: Protect the account by
matching incoming statements against the account
whitelist.
RECORDING
: Training mode: Record
acceptable statements for the account. Incoming
statements that do not immediately fail with a syntax
error are recorded to become part of the account
whitelist rules.
RESET
: Clear the account whitelist
and set the account mode to OFF
.
Switching the mode for an account to any mode but
RECORDING
synchronizes the firewall
cache data to the underlying mysql
system database tables for persistent storage. Switching
the mode from OFF
to
RECORDING
reloads the whitelist from
the mysql.firewall_whitelist
table into
the cache.
If an account has an empty whitelist, setting its mode to
PROTECTING
produces an error message
that is returned in a result set, but not an SQL error:
mysql> CALL mysql.sp_set_firewall_mode('a@b','PROTECTING');
+----------------------------------------------------------------------+
| set_firewall_mode(arg_userhost, arg_mode) |
+----------------------------------------------------------------------+
| ERROR: PROTECTING mode requested for a@b but the whitelist is empty. |
+----------------------------------------------------------------------+
1 row in set (0.02 sec)
Query OK, 0 rows affected (0.02 sec)
mysql_firewall_flush_status()
This UDF resets several firewall status variables to 0:
Firewall_access_denied Firewall_access_granted Firewall_access_suspicious
Example:
SELECT mysql_firewall_flush_status();
normalize_statement(
stmt
)
This UDF normalizes a SQL statement into the digest form used for whitelist rules.
Example:
SELECT normalize_statement('SELECT * FROM t1 WHERE c1 > 2');
read_firewall_users(
user
,
mode
)
This aggregate UDF updates the firewall user cache through
a SELECT
statement on the
mysql.firewall_users
table.
Example:
SELECT read_firewall_users('fwuser@localhost', 'RECORDING') FROM mysql.firewall_users;
read_firewall_whitelist(
user
,
rule
)
This aggregate UDF updates the recorded statement cache
through a SELECT
statement on the
mysql.firewall_whitelist
table.
Example:
SELECT read_firewall_whitelist('fwuser@localhost', 'RECORDING') FROM mysql.firewall_whitelist;
set_firewall_mode(
user
,
mode
)
This UDF manages the user cache and establishes the user operational mode.
Example:
SELECT set_firewall_mode('fwuser@localhost', 'RECORDING');
MySQL Enterprise Firewall supports the following system variables. Use them to configure firewall operation. These variables are unavailable unless the firewall is installed (see Section 6.4.5.2, “Installing or Uninstalling MySQL Enterprise Firewall”).
Introduced | 5.7.9 | ||
Command-Line Format | --mysql_firewall_mode={OFF|ON} | ||
System Variable | Name | mysql_firewall_mode | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | boolean | |
Default | ON |
Whether MySQL Enterprise Firewall is enabled (the default) or disabled.
Introduced | 5.7.9 | ||
Command-Line Format | --mysql_firewall_trace={OFF|ON} | ||
System Variable | Name | mysql_firewall_trace | |
Variable Scope | Global | ||
Dynamic Variable | Yes | ||
Permitted Values | Type | boolean | |
Default | OFF |
Whether the MySQL Enterprise Firewall trace is enabled or disabled (the
default). When
mysql_firewall_trace
is
enabled, for PROTECTING
mode, the
firewall writes rejected statements to the error log.
MySQL Enterprise Firewall supports the following status variables. Use them to
obtain information about firewall operational status. These
variables are unavailable unless the firewall is installed
(see Section 6.4.5.2, “Installing or Uninstalling MySQL Enterprise Firewall”). Firewall status
variables are set to 0 whenever the
MYSQL_FIREWALL
plugin is installed or the
server is started. Many of them are reset to zero by the
mysql_firewall_flush_status()
UDF (see
Section 6.4.5.4.2, “MySQL Enterprise Firewall Procedures and Functions”).
The number of statements rejected by MySQL Enterprise Firewall.
The number of statements accepted by MySQL Enterprise Firewall.
The number of statements logged by MySQL Enterprise Firewall as suspicious
for users who are in DETECTING
mode.
The number of statements recorded by MySQL Enterprise Firewall, including duplicates.