diff options
Diffstat (limited to 'modules/pam_faillock/README')
| -rw-r--r-- | modules/pam_faillock/README | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/modules/pam_faillock/README b/modules/pam_faillock/README new file mode 100644 index 00000000..c88705ad --- /dev/null +++ b/modules/pam_faillock/README @@ -0,0 +1,140 @@ +pam_faillock — Module counting authentication failures during a specified +interval + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +DESCRIPTION + +This module maintains a list of failed authentication attempts per user during +a specified interval and locks the account in case there were more than deny +consecutive failed authentications. + +Normally, failed attempts to authenticate root will not cause the root account +to become blocked, to prevent denial-of-service: if your users aren't given +shell accounts and root may only login via su or at the machine console (not +telnet/rsh, etc), this is safe. + +OPTIONS + +{preauth|authfail|authsucc} + + This argument must be set accordingly to the position of this module + instance in the PAM stack. + + The preauth argument must be used when the module is called before the + modules which ask for the user credentials such as the password. The module + just examines whether the user should be blocked from accessing the service + in case there were anomalous number of failed consecutive authentication + attempts recently. This call is optional if authsucc is used. + + The authfail argument must be used when the module is called after the + modules which determine the authentication outcome, failed. Unless the user + is already blocked due to previous authentication failures, the module will + record the failure into the appropriate user tally file. + + The authsucc argument must be used when the module is called after the + modules which determine the authentication outcome, succeeded. Unless the + user is already blocked due to previous authentication failures, the module + will then clear the record of the failures in the respective user tally + file. Otherwise it will return authentication error. If this call is not + done, the pam_faillock will not distinguish between consecutive and + non-consecutive failed authentication attempts. The preauth call must be + used in such case. Due to complications in the way the PAM stack can be + configured it is also possible to call pam_faillock as an account module. + In such configuration the module must be also called in the preauth stage. + +conf=/path/to/config-file + + Use another configuration file instead of the default /etc/security/ + faillock.conf. + +The options for configuring the module behavior are described in the +faillock.conf(5) manual page. The options specified on the module command line +override the values from the configuration file. + +NOTES + +Configuring options on the module command line is not recommend. The /etc/ +security/faillock.conf should be used instead. + +The setup of pam_faillock in the PAM stack is different from the pam_tally2 +module setup. + +Individual files with the failure records are created as owned by the user. +This allows pam_faillock.so module to work correctly when it is called from a +screensaver. + +Note that using the module in preauth without the silent option specified in / +etc/security/faillock.conf or with requisite control field leaks an information +about existence or non-existence of an user account in the system because the +failures are not recorded for the unknown users. The message about the user +account being locked is never displayed for non-existing user accounts allowing +the adversary to infer that a particular account is not existing on a system. + +EXAMPLES + +Here are two possible configuration examples for /etc/pam.d/login. They make +pam_faillock to lock the account after 4 consecutive failed logins during the +default interval of 15 minutes. Root account will be locked as well. The +accounts will be automatically unlocked after 20 minutes. + +In the first example the module is called only in the auth phase and the module +does not print any information about the account being blocked by pam_faillock. +The preauth call can be added to tell users that their logins are blocked by +the module and also to abort the authentication without even asking for +password in such case. + +/etc/security/faillock.conf file example: + +deny=4 +unlock_time=1200 +silent + + +/etc/pam.d/config file example: + +auth required pam_securetty.so +auth required pam_env.so +auth required pam_nologin.so +# optionally call: auth requisite pam_faillock.so preauth +# to display the message about account being locked +auth [success=1 default=bad] pam_unix.so +auth [default=die] pam_faillock.so authfail +auth sufficient pam_faillock.so authsucc +auth required pam_deny.so +account required pam_unix.so +password required pam_unix.so shadow +session required pam_selinux.so close +session required pam_loginuid.so +session required pam_unix.so +session required pam_selinux.so open + + +In the second example the module is called both in the auth and account phases +and the module informs the authenticating user when the account is locked if +silent option is not specified in the faillock.conf. + +auth required pam_securetty.so +auth required pam_env.so +auth required pam_nologin.so +auth required pam_faillock.so preauth +# optionally use requisite above if you do not want to prompt for the password +# on locked accounts +auth sufficient pam_unix.so +auth [default=die] pam_faillock.so authfail +auth required pam_deny.so +account required pam_faillock.so +# if you drop the above call to pam_faillock.so the lock will be done also +# on non-consecutive authentication failures +account required pam_unix.so +password required pam_unix.so shadow +session required pam_selinux.so close +session required pam_loginuid.so +session required pam_unix.so +session required pam_selinux.so open + + +AUTHOR + +pam_faillock was written by Tomas Mraz. + |