4.4.10 Writing Password-Validation Plugins

This section describes how to write a server-side password-validation plugin. The instructions are based on the source code in the plugin/password_validation directory of MySQL source distributions. The validate_password.cc source file in that directory implements the plugin named validate_password.

Note

In MySQL 8.0.4, the validate_password plugin was reimplemented as the validate_password component. The plugin form of validate_password is still available but is now deprecated and will be removed in a future version of MySQL. MySQL installations that use the plugin should make the transition to using the component instead. See Transitioning to the Password Validation Component.

To write a password-validation plugin, include the following header file in the plugin source file. Other MySQL or general header files might also be needed, depending on the plugin capabilities and requirements.

#include <mysql/plugin_validate_password.h>

plugin_validate_password.h includes plugin.h, so you need not include the latter file explicitly. plugin.h defines the MYSQL_VALIDATE_PASSWORD_PLUGIN server plugin type and the data structures needed to declare the plugin. plugin_validate_password.h defines data structures specific to password-validation plugins.

A password-validation plugin, like any MySQL server plugin, has a general plugin descriptor (see Section 4.4.2.1, “Server Plugin Library and Plugin Descriptors”). In validate_password.cc, the general descriptor for validate_password looks like this:

mysql_declare_plugin(validate_password)
{
  MYSQL_VALIDATE_PASSWORD_PLUGIN,     /*   type                            */
  &validate_password_descriptor,      /*   descriptor                      */
  "validate_password",                /*   name                            */
  "Oracle Corporation",               /*   author                          */
  "check password strength",          /*   description                     */
  PLUGIN_LICENSE_GPL,
  validate_password_init,             /*   init function (when loaded)     */
  validate_password_deinit,           /*   deinit function (when unloaded) */
  0x0100,                             /*   version                         */
  NULL,
  validate_password_system_variables, /*   system variables                */
  NULL,
  0,
}
mysql_declare_plugin_end;

The name member (validate_password) indicates the name to use for references to the plugin in statements such as INSTALL PLUGIN or UNINSTALL PLUGIN. This is also the name displayed by INFORMATION_SCHEMA.PLUGINS or SHOW PLUGINS.

The general descriptor also refers to validate_password_system_variables, a structure that exposes several system variables to the SHOW VARIABLES statement:

static struct st_mysql_sys_var* validate_password_system_variables[]= {
  MYSQL_SYSVAR(length),
  MYSQL_SYSVAR(number_count),
  MYSQL_SYSVAR(mixed_case_count),
  MYSQL_SYSVAR(special_char_count),
  MYSQL_SYSVAR(policy),
  MYSQL_SYSVAR(dictionary_file),
  NULL
};

The validate_password_init initialization function reads the dictionary file if one was specified, and the validate_password_deinit function frees data structures associated with the file.

The validate_password_descriptor value in the general descriptor points to the type-specific descriptor. For password-validation plugins, this descriptor has the following structure:

struct st_mysql_validate_password
{
  int interface_version;
  /*
    This function returns TRUE for passwords which satisfy the password
    policy (as chosen by plugin variable) and FALSE for all other
    password
  */
  int (*validate_password)(mysql_string_handle password);
  /*
    This function returns the password strength (0-100) depending
    upon the policies
  */
  int (*get_password_strength)(mysql_string_handle password);
};

The type-specific descriptor has these members:

• interface_version: By convention, type-specific plugin descriptors begin with the interface version for the given plugin type. The server checks interface_version when it loads the plugin to see whether the plugin is compatible with it. For password-validation plugins, the value of the interface_version member is MYSQL_VALIDATE_PASSWORD_INTERFACE_VERSION (defined in plugin_validate_password.h).

• validate_password: A function that the server calls to test whether a password satisfies the current password policy. It returns 1 if the password is okay and 0 otherwise. The argument is the password, passed as a mysql_string_handle value. This data type is implemented by the mysql_string server service. For details, see the string_service.h and string_service.cc source files in the sql directory.

• get_password_strength: A function that the server calls to assess the strength of a password. It returns a value from 0 (weak) to 100 (strong). The argument is the password, passed as a mysql_string_handle value.

For the validate_password plugin, the type-specific descriptor looks like this:

static struct st_mysql_validate_password validate_password_descriptor=
{
  MYSQL_VALIDATE_PASSWORD_INTERFACE_VERSION,
  validate_password,                         /* validate function          */
  get_password_strength                      /* validate strength function */
};

To compile and install a plugin library file, use the instructions in Section 4.4.3, “Compiling and Installing Plugin Libraries”. To make the library file available for use, install it in the plugin directory (the directory named by the plugin_dir system variable). For the validate_password plugin, it is compiled and installed when you build MySQL from source. It is also included in binary distributions. The build process produces a shared object library with a name of validate_password.so (the .so suffix might differ depending on your platform).

To register the plugin at runtime, use this statement, adjusting the .so suffix for your platform as necessary:

INSTALL PLUGIN validate_password SONAME 'validate_password.so';

For additional information about plugin loading, see Installing and Uninstalling Plugins.

To verify plugin installation, examine the INFORMATION_SCHEMA.PLUGINS table or use the SHOW PLUGINS statement. See Obtaining Server Plugin Information.

While the validate_password plugin is installed, it exposes system variables that indicate the password-checking parameters:

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      |
+--------------------------------------+--------+

For descriptions of these variables, see Password Validation Options and Variables.

To disable the plugin after testing it, use this statement to unload it:

UNINSTALL PLUGIN validate_password;