MySQL 8.0 Release Notes
MySQL 8.0 Source Code Documentation
Pre-General Availability Draft: 2017-07-17
To control the activation of the
validate_password plugin, use this option:
-
Command-Line Format --validate-password[=value]Permitted Values Type enumeration Default ONValid Values ONOFFFORCEFORCE_PLUS_PERMANENTThis option controls how the server loads the
validate_passwordplugin at startup. The value should be one of those available for plugin-loading options, as described in Section 5.6.2, “Installing and Uninstalling Plugins”. For example,--validate-password=FORCE_PLUS_PERMANENTtells 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_passwordplugin has been previously registered withINSTALL PLUGINor is loaded with--plugin-load-add. See Section 6.5.3.1, “Password Validation Plugin Installation”.
If the validate_password plugin is enabled,
it exposes several system variables representing the parameters
that control password checking:
mysql> SHOW VARIABLES LIKE 'validate_password%';
+--------------------------------------+--------+
| Variable_name | Value |
+--------------------------------------+--------+
| validate_password_check_user_name | ON |
| 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 these system variables at server startup or at runtime. The following list describes the meaning of each variable.
validate_password_check_user_nameCommand-Line Format --validate-password-check-user-nameSystem Variable Name validate_password_check_user_nameVariable Scope Global Dynamic Variable Yes Permitted Values Type boolean Default ONWhether passwords are compared to the user name part of the effective user account for the current session and rejected if they match. By default,
validate_password_check_user_nameis enabled. This variable controls user name matching independent of the value ofvalidate_password_policy.When
validate_password_check_user_nameis enabled, it has these effects:Checking occurs in all contexts for which the
validate_passwordplugin is invoked, which includes statements such asALTER USERandSET PASSWORD, and invocation of functions such asPASSWORD()andVALIDATE_PASSWORD_STRENGTH().If a password is the same as the user name or its reverse, a match occurs and the password is rejected.
If a password matches the user name,
VALIDATE_PASSWORD_STRENGTH()returns 0 regardless of how othervalidate_passwordsystem variables are set.The user names used for comparison are taken from the values of the
USER()andCURRENT_USER()functions for the current session. (An implication is that a user who has theSUPERprivilege can execute a statement to set another user's password to that user name, and cannot set that user's password to the name of the user executing the statement.)Only the user name part of the
USER()andCURRENT_USER()function values is used, not the host name part. If a user name is empty, no comparison is done.User name matching is case sensitive. The password and user name values are compared as binary strings on a byte-by-byte basis.
validate_password_dictionary_fileSystem Variable Name validate_password_dictionary_fileVariable Scope Global Dynamic Variable Yes Permitted Values Type file name The path name of the dictionary file used by the
validate_passwordplugin 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 thevalidate_password_policysystem 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, includingSTRONG, so the strength assessment includes the dictionary check regardless of thevalidate_password_policyvalue.validate_password_dictionary_filecan be set at runtime and assigning a value causes the named file to be read without a restart.-
System Variable Name validate_password_lengthVariable Scope Global Dynamic Variable Yes Permitted Values Type integer Default 8Min Value 0The minimum number of characters that passwords checked by the
validate_passwordplugin must have. This variable is unavailable unless that plugin is installed.The
validate_password_lengthminimum 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_passwordplugin adjusts the value ofvalidate_password_lengthdue to the preceding constraint, it writes a message to the error log. validate_password_mixed_case_countSystem Variable Name validate_password_mixed_case_countVariable Scope Global Dynamic Variable Yes Permitted Values Type integer Default 1Min Value 0The minimum number of lowercase and uppercase characters that passwords checked by the
validate_passwordplugin must have if the password policy isMEDIUMor stronger. For a given value, the password must have that many lowercase characters, and that many uppercase characters. This variable is unavailable unless that plugin is installed.validate_password_number_countSystem Variable Name validate_password_number_countVariable Scope Global Dynamic Variable Yes Permitted Values Type integer Default 1Min Value 0The minimum number of numeric (digit) characters that passwords checked by the
validate_passwordplugin must have if the password policy isMEDIUMor stronger. This variable is unavailable unless that plugin is installed.-
System Variable Name validate_password_policyVariable Scope Global Dynamic Variable Yes Permitted Values Type enumeration Default 1Valid Values 012The password policy enforced by the
validate_passwordplugin. This variable is unavailable unless that plugin is installed.validate_password_policyaffects how the plugin uses its other policy-setting system variables, except for checking passwords against user names, which is controlled independently byvalidate_password_check_user_name.The
validate_password_policyvalue can be specified using numeric values 0, 1, 2, or the corresponding symbolic valuesLOW,MEDIUM,STRONG. The following table describes the tests performed for each policy. For the length test, the required length is the value of thevalidate_password_lengthsystem variable. Similarly, the required values for the other tests are given by othervalidate_password_variables.xxxPolicy Tests Performed 0orLOWLength 1orMEDIUMLength; numeric, lowercase/uppercase, and special characters 2orSTRONGLength; numeric, lowercase/uppercase, and special characters; dictionary file validate_password_special_char_countSystem Variable Name validate_password_special_char_countVariable Scope Global Dynamic Variable Yes Permitted Values Type integer Default 1Min Value 0The minimum number of nonalphanumeric characters that passwords checked by the
validate_passwordplugin must have if the password policy isMEDIUMor stronger. This variable is unavailable unless that plugin is installed.
If the validate_password plugin is enabled,
it exposes 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 status variable.
validate_password_dictionary_file_last_parsedWhen the dictionary file was last parsed.
validate_password_dictionary_file_words_countThe number of words read from the dictionary file.