diff options
Diffstat (limited to '')
-rw-r--r-- | modules/pam_faillock/pam_faillock.8 | 262 | ||||
-rw-r--r-- | modules/pam_faillock/pam_faillock.8.xml | 362 |
2 files changed, 624 insertions, 0 deletions
diff --git a/modules/pam_faillock/pam_faillock.8 b/modules/pam_faillock/pam_faillock.8 new file mode 100644 index 0000000..593b1fe --- /dev/null +++ b/modules/pam_faillock/pam_faillock.8 @@ -0,0 +1,262 @@ +'\" t +.\" Title: pam_faillock +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> +.\" Date: 06/08/2020 +.\" Manual: Linux-PAM Manual +.\" Source: Linux-PAM Manual +.\" Language: English +.\" +.TH "PAM_FAILLOCK" "8" "06/08/2020" "Linux-PAM Manual" "Linux\-PAM Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pam_faillock \- Module counting authentication failures during a specified interval +.SH "SYNOPSIS" +.HP \w'\fBauth\ \&.\&.\&.\ pam_faillock\&.so\fR\ 'u +\fBauth \&.\&.\&. pam_faillock\&.so\fR {preauth|authfail|authsucc} [conf=\fI/path/to/config\-file\fR] [dir=\fI/path/to/tally\-directory\fR] [even_deny_root] [deny=\fIn\fR] [fail_interval=\fIn\fR] [unlock_time=\fIn\fR] [root_unlock_time=\fIn\fR] [admin_group=\fIname\fR] [audit] [silent] [no_log_info] +.HP \w'\fBaccount\ \&.\&.\&.\ pam_faillock\&.so\fR\ 'u +\fBaccount \&.\&.\&. pam_faillock\&.so\fR [dir=\fI/path/to/tally\-directory\fR] [no_log_info] +.SH "DESCRIPTION" +.PP +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 +\fIdeny\fR +consecutive failed authentications\&. +.PP +Normally, failed attempts to authenticate +\fIroot\fR +will +\fBnot\fR +cause the root account to become blocked, to prevent denial\-of\-service: if your users aren\*(Aqt given shell accounts and root may only login via +\fBsu\fR +or at the machine console (not telnet/rsh, etc), this is safe\&. +.SH "OPTIONS" +.PP +\fB{preauth|authfail|authsucc}\fR +.RS 4 +This argument must be set accordingly to the position of this module instance in the PAM stack\&. +.sp +The +\fIpreauth\fR +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 +\fIauthsucc\fR +is used\&. +.sp +The +\fIauthfail\fR +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\&. +.sp +The +\fIauthsucc\fR +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 +\fIpreauth\fR +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 +\fIpam_faillock\fR +as an account module\&. In such configuration the module must be also called in the +\fIpreauth\fR +stage\&. +.RE +.PP +\fBconf=/path/to/config\-file\fR +.RS 4 +Use another configuration file instead of the default +/etc/security/faillock\&.conf\&. +.RE +.PP +The options for configuring the module behavior are described in the +\fBfaillock.conf\fR(5) +manual page\&. The options specified on the module command line override the values from the configuration file\&. +.SH "MODULE TYPES PROVIDED" +.PP +The +\fBauth\fR +and +\fBaccount\fR +module types are provided\&. +.SH "RETURN VALUES" +.PP +PAM_AUTH_ERR +.RS 4 +An invalid option was given, the module was not able to retrieve the user name, no valid counter file was found, or too many failed logins\&. +.RE +.PP +PAM_BUF_ERR +.RS 4 +Memory buffer error\&. +.RE +.PP +PAM_CONV_ERR +.RS 4 +The conversation method supplied by the application failed to obtain the username\&. +.RE +.PP +PAM_INCOMPLETE +.RS 4 +The conversation method supplied by the application returned PAM_CONV_AGAIN\&. +.RE +.PP +PAM_SUCCESS +.RS 4 +Everything was successful\&. +.RE +.PP +PAM_IGNORE +.RS 4 +User not present in passwd database\&. +.RE +.SH "NOTES" +.PP +Configuring options on the module command line is not recommend\&. The +/etc/security/faillock\&.conf +should be used instead\&. +.PP +The setup of +\fIpam_faillock\fR +in the PAM stack is different from the +\fIpam_tally2\fR +module setup\&. +.PP +Individual files with the failure records are created as owned by the user\&. This allows +\fBpam_faillock\&.so\fR +module to work correctly when it is called from a screensaver\&. +.PP +Note that using the module in +\fBpreauth\fR +without the +\fBsilent\fR +option specified in +/etc/security/faillock\&.conf +or with +\fIrequisite\fR +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\&. +.SH "EXAMPLES" +.PP +Here are two possible configuration examples for +/etc/pam\&.d/login\&. They make +\fIpam_faillock\fR +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\&. +.PP +In the first example the module is called only in the +\fIauth\fR +phase and the module does not print any information about the account being blocked by +\fIpam_faillock\fR\&. The +\fIpreauth\fR +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\&. +.PP +/etc/security/faillock\&.conf +file example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +deny=4 +unlock_time=1200 +silent + +.fi +.if n \{\ +.RE +.\} +.PP +/etc/pam\&.d/config file example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +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 + +.fi +.if n \{\ +.RE +.\} +.PP +In the second example the module is called both in the +\fIauth\fR +and +\fIaccount\fR +phases and the module informs the authenticating user when the account is locked if +\fBsilent\fR +option is not specified in the +faillock\&.conf\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +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 + +.fi +.if n \{\ +.RE +.\} +.SH "FILES" +.PP +/var/run/faillock/* +.RS 4 +the files logging the authentication failures for users +.RE +.PP +/etc/security/faillock\&.conf +.RS 4 +the config file for pam_faillock options +.RE +.SH "SEE ALSO" +.PP +\fBfaillock\fR(8), +\fBfaillock.conf\fR(5), +\fBpam.conf\fR(5), +\fBpam.d\fR(5), +\fBpam\fR(8) +.SH "AUTHOR" +.PP +pam_faillock was written by Tomas Mraz\&. diff --git a/modules/pam_faillock/pam_faillock.8.xml b/modules/pam_faillock/pam_faillock.8.xml new file mode 100644 index 0000000..f43b401 --- /dev/null +++ b/modules/pam_faillock/pam_faillock.8.xml @@ -0,0 +1,362 @@ +<?xml version="1.0" encoding='UTF-8'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<refentry id="pam_faillock"> + + <refmeta> + <refentrytitle>pam_faillock</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo> + </refmeta> + + <refnamediv id="pam_faillock-name"> + <refname>pam_faillock</refname> + <refpurpose>Module counting authentication failures during a specified interval</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="pam_faillock-cmdsynopsisauth"> + <command>auth ... pam_faillock.so</command> + <arg choice="req"> + preauth|authfail|authsucc + </arg> + <arg choice="opt"> + conf=<replaceable>/path/to/config-file</replaceable> + </arg> + <arg choice="opt"> + dir=<replaceable>/path/to/tally-directory</replaceable> + </arg> + <arg choice="opt"> + even_deny_root + </arg> + <arg choice="opt"> + deny=<replaceable>n</replaceable> + </arg> + <arg choice="opt"> + fail_interval=<replaceable>n</replaceable> + </arg> + <arg choice="opt"> + unlock_time=<replaceable>n</replaceable> + </arg> + <arg choice="opt"> + root_unlock_time=<replaceable>n</replaceable> + </arg> + <arg choice="opt"> + admin_group=<replaceable>name</replaceable> + </arg> + <arg choice="opt"> + audit + </arg> + <arg choice="opt"> + silent + </arg> + <arg choice="opt"> + no_log_info + </arg> + </cmdsynopsis> + <cmdsynopsis id="pam_faillock-cmdsynopsisacct"> + <command>account ... pam_faillock.so</command> + <arg choice="opt"> + dir=<replaceable>/path/to/tally-directory</replaceable> + </arg> + <arg choice="opt"> + no_log_info + </arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="pam_faillock-description"> + + <title>DESCRIPTION</title> + + <para> + 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 <replaceable>deny</replaceable> consecutive + failed authentications. + </para> + <para> + Normally, failed attempts to authenticate <emphasis>root</emphasis> will + <emphasis remap='B'>not</emphasis> 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 <command>su</command> or + at the machine console (not telnet/rsh, etc), this is safe. + </para> + </refsect1> + + <refsect1 id="pam_faillock-options"> + + <title>OPTIONS</title> + <variablelist> + <varlistentry> + <term> + <option>{preauth|authfail|authsucc}</option> + </term> + <listitem> + <para> + This argument must be set accordingly to the position of this module + instance in the PAM stack. + </para> + <para> + The <emphasis>preauth</emphasis> 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 <emphasis>authsucc</emphasis> is used. + </para> + <para> + The <emphasis>authfail</emphasis> 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. + </para> + <para> + The <emphasis>authsucc</emphasis> 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 + <emphasis>preauth</emphasis> 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 <emphasis>pam_faillock</emphasis> as an account module. + In such configuration the module must be also called in the + <emphasis>preauth</emphasis> stage. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>conf=/path/to/config-file</option> + </term> + <listitem> + <para> + Use another configuration file instead of the default + <filename>/etc/security/faillock.conf</filename>. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + The options for configuring the module behavior are described in the + <citerefentry><refentrytitle>faillock.conf</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> manual page. The options specified on the module command + line override the values from the configuration file. + </para> + </refsect1> + + <refsect1 id="pam_faillock-types"> + <title>MODULE TYPES PROVIDED</title> + <para> + The <option>auth</option> and <option>account</option> module types are + provided. + </para> + </refsect1> + + <refsect1 id='pam_faillock-return_values'> + <title>RETURN VALUES</title> + <variablelist> + <varlistentry> + <term>PAM_AUTH_ERR</term> + <listitem> + <para> + An invalid option was given, the module was not able + to retrieve the user name, no valid counter file + was found, or too many failed logins. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_BUF_ERR</term> + <listitem> + <para> + Memory buffer error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_CONV_ERR</term> + <listitem> + <para> + The conversation method supplied by the application + failed to obtain the username. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_INCOMPLETE</term> + <listitem> + <para> + The conversation method supplied by the application + returned PAM_CONV_AGAIN. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_SUCCESS</term> + <listitem> + <para> + Everything was successful. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_IGNORE</term> + <listitem> + <para> + User not present in passwd database. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='pam_faillock-notes'> + <title>NOTES</title> + <para> + Configuring options on the module command line is not recommend. The + <filename>/etc/security/faillock.conf</filename> should be used instead. + </para> + <para> + The setup of <emphasis>pam_faillock</emphasis> in the PAM stack is different + from the <emphasis>pam_tally2</emphasis> module setup. + </para> + <para> + Individual files with the failure records are created as owned by + the user. This allows <emphasis remap='B'>pam_faillock.so</emphasis> module + to work correctly when it is called from a screensaver. + </para> + <para> + Note that using the module in <option>preauth</option> without the + <option>silent</option> option specified in <filename>/etc/security/faillock.conf</filename> + or with <emphasis>requisite</emphasis> 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. + </para> + </refsect1> + + <refsect1 id='pam_faillock-examples'> + <title>EXAMPLES</title> + <para> + Here are two possible configuration examples for <filename>/etc/pam.d/login</filename>. + They make <emphasis>pam_faillock</emphasis> 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. + </para> + <para> + In the first example the module is called only in the <emphasis>auth</emphasis> + phase and the module does not print any information about the account being blocked + by <emphasis>pam_faillock</emphasis>. The <emphasis>preauth</emphasis> 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. + </para> + <para> + <filename>/etc/security/faillock.conf</filename> file example: + </para> + <programlisting> +deny=4 +unlock_time=1200 +silent + </programlisting> + <para> + /etc/pam.d/config file example: + </para> + <programlisting> +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 + </programlisting> + <para> + In the second example the module is called both in the <emphasis>auth</emphasis> + and <emphasis>account</emphasis> phases and the module informs the authenticating + user when the account is locked if <option>silent</option> option is not + specified in the <filename>faillock.conf</filename>. + </para> + <programlisting> +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 + </programlisting> + </refsect1> + + <refsect1 id="pam_faillock-files"> + <title>FILES</title> + <variablelist> + <varlistentry> + <term><filename>/var/run/faillock/*</filename></term> + <listitem> + <para>the files logging the authentication failures for users</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>/etc/security/faillock.conf</filename></term> + <listitem> + <para>the config file for pam_faillock options</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='pam_faillock-see_also'> + <title>SEE ALSO</title> + <para> + <citerefentry> + <refentrytitle>faillock</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>faillock.conf</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum> + </citerefentry> + </para> + </refsect1> + + <refsect1 id='pam_faillock-author'> + <title>AUTHOR</title> + <para> + pam_faillock was written by Tomas Mraz. + </para> + </refsect1> + +</refentry> |