29.2.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.

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 29.2.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:

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 29.2.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 (adjust the .so suffix for your platform as necessary):

For additional information about plugin loading, see Section 5.6.1, “Installing and Uninstalling Plugins”.

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

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

For descriptions of these variables, see Section 6.4.3.2, “Password Validation Options and Variables”.

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