This section describes how to write a password-validation server 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 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.

#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 23.2.4.2.1, "Server Plugin Library and Plugin Descriptors"). In validate_password.cc, the general descriptor 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 object file, use the instructions in Section 23.2.4.3, "Compiling and Installing Plugin Libraries". To use the library file, it must be installed 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 extension might be be different depending on your platform).

To register the plugin at runtime, use this statement (change the extension as necessary):

mysql> INSTALL PLUGIN validate_password SONAME
        'validate_password.so';

For additional information about plugin loading, 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.

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 Section 6.1.2.6.2, "Password Validation Plugin Options and Variables".

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

mysql> UNINSTALL PLUGIN
        validate_password;