Password Validation Plugin API - Source

Revision

77794

User

Sergei Golubchik

Date

2019-01-16 00:29

<<product mariadb from=10.1.2>> Starting from 10.1.2, MariaDB implements the Password Validation Plugin API <</product>> “Password validation” means ensuring that user passwords meet certain minimal security requirements. A dedicated plugin API allows the creation of password validation plugins that will check user passwords as they are set (in [[set-password|##SET PASSWORD##]] and [[grant|##GRANT##]] statements) and either allow or reject them. == SQL-level extensions MariaDB comes with two password validation plugins — the [[simple_password_check]] plugin and the [[cracklib_password_check]] plugin. They are not enabled by default; use [[install-soname|##INSTALL SONAME##]] (or [[install-plugin|##INSTALL PLUGIN##]]) statement to install them. When at least one password plugin is loaded, all new passwords will be validated and password-changing statements will fail if the password will not pass validation checks. Several password validation plugin can be loaded at the same time — in this case a password must pass **all** validation checks by **all** plugins. === Password-changing statements One can use various SQL statements to change a user password: ==== With plain text password: <<sql>> SET PASSWORD = PASSWORD('plain-text password'); SET PASSWORD FOR `user`@`host` = PASSWORD('plain-text password'); SET PASSWORD = OLD_PASSWORD('plain-text password'); SET PASSWORD FOR `user`@`host` = OLD_PASSWORD('plain-text password'); CREATE USER `user`@`host` IDENTIFIED BY 'plain-text password'; GRANT privileges TO `user`@`host` IDENTIFIED BY 'plain-text password'; <</sql>> These statements are subject to password validation. If at least one password validation plugin is loaded, plain-text passwords specified in these statements will be validated. ==== With password hash: <<sql>> SET PASSWORD = 'password hash'; SET PASSWORD FOR `user`@`host` = 'password hash'; CREATE USER `user`@`host` IDENTIFIED BY PASSWORD 'password hash'; CREATE USER `user`@`host` IDENTIFIED VIA mysql_native_password USING 'password hash'; CREATE USER `user`@`host` IDENTIFIED VIA mysql_old_password USING 'password hash'; GRANT privileges TO `user`@`host` IDENTIFIED BY PASSWORD 'password hash'; GRANT privileges TO `user`@`host` IDENTIFIED VIA mysql_native_password USING 'password hash'; GRANT privileges TO `user`@`host` IDENTIFIED VIA mysql_old_password USING 'password hash'; <</sql>> These statements can not possibly use password validation — there is nothing to validate, the original plain-text password is not available. MariaDB introduces a **strict password validation** mode — controlled by a [[server-system-variables#strict_password_validation|strict_password_validation]] global server variable. If the strict password validation is enabled and at least one password validation plugin is loaded then these “unvalidatable” passwords will be rejected. Otherwise they will be accepted. By default a strict password validation is enabled (but note that it has no effect if no password validation plugin is loaded). ==== Direct updates: <<sql>> UPDATE mysql.user SET password='password hash' WHERE user='user' AND host='host'; FLUSH PRIVILEGES; <</sql>> Direct updates of privilege tables are not validated either. But unlike dedicated password changing statements, direct updates are not affected by the ##strict_password_validation## variable. Do not give untrusted users write access to the ##mysql## database, otherwise they will be able to bypass password validation (frankly, they will be able to do a lot more than that, so if untrusted users can write to privilege tables, password validation will probably be the least of your problems). == Examples Failed password validation: <<code>> MariaDB []> grant select on *.* to foobar identified by 'raboof'; ERROR HY000: Your password does not satisfy the current policy requirements MariaDB []> show warnings; +---------+------+----------------------------------------------------------------+ | Level | Code | Message | +---------+------+----------------------------------------------------------------+ | Warning | 1819 | cracklib: it is based on your username | | Error | 1819 | Your password does not satisfy the current policy requirements | +---------+------+----------------------------------------------------------------+ <</code>> Strict password validation: <<code>> MariaDB []> grant select on *.* to foo identified by password '2222222222222222'; ERROR HY000: The MariaDB server is running with the --strict-password-validation option so it cannot execute this statement <</code>> == Plugin API Password validation plugin API is very simple. A plugin must implement only one method — ##validate_password()##. This method takes two arguments — user name and the plain-text password. And it returns 0 when the password has passed the validation and 1 otherwise, See also ##mysql/plugin_password_validation.h## and password validation plugins in ##plugin/simple_password_check/## and ##plugins/cracklib_password_check/##.