freebsd-dev/contrib/libpam/doc/modules/pam_deny.sgml

<!--
   $Id: pam_deny.sgml,v 1.3 1997/02/15 18:25:44 morgan Exp morgan $
   
   This file was written by Andrew G. Morgan <morgan@parc.power.net>
-->

<sect1>The locking-out module

<sect2>Synopsis

<p>
<descrip>

<tag><bf>Module Name:</bf></tag>
pam_deny

<tag><bf>Author:</bf></tag>
Andrew G. Morgan &lt;morgan@parc.power.net&gt;

<tag><bf>Maintainer:</bf></tag>
current <bf/Linux-PAM/ maintainer

<tag><bf>Management groups provided:</bf></tag>
account; authentication; password; session

<tag><bf>Cryptographically sensitive:</bf></tag>

<tag><bf>Security rating:</bf></tag>

<tag><bf>Clean code base:</bf></tag>
clean.

<tag><bf>System dependencies:</bf></tag>

<tag><bf>Network aware:</bf></tag>

</descrip>

<sect2>Overview of module

<p>
This module can be used to deny access. It always indicates a failure
to the application through the PAM framework. As is commented in the
overview section <ref id="overview-section" name="above">, this module
might be suitable for using for default (the <tt/OTHER/) entries.

<sect2>Account component

<p>
<descrip>

<tag><bf>Recognized arguments:</bf></tag>

<tag><bf>Description:</bf></tag>

This component does nothing other than return a failure. The
failure type is <tt/PAM_ACCT_EXPIRED/.

<tag><bf>Examples/suggested usage:</bf></tag>

Stacking this module with type <tt/account/ will prevent the user from
gaining access to the system via applications that refer to
<bf/Linux-PAM/'s account management function <tt/pam_acct_mgmt()/.

<p>
The following example would make it impossible to login:
<tscreen>
<verb>
#
# add this line to your other login entries to disable all accounts
#
login	account	 required	pam_deny.so
</verb>
</tscreen>

</descrip>

<sect2>Authentication component

<p>
<descrip>

<tag><bf>Recognized arguments:</bf></tag>

<tag><bf>Description:</bf></tag>

This component does nothing other than return a failure. The failure
type is <tt/PAM_AUTH_ERR/ in the case that <tt/pam_authenticate()/ is
called (when the application tries to authenticate the user), and is
<tt/PAM_CRED_UNAVAIL/ when the application calls <tt/pam_setcred()/
(to establish and set the credentials of the user -- it is unlikely
that this function will ever be called in practice).

<tag><bf>Examples/suggested usage:</bf></tag>

To deny access to default applications with this component of the
<tt/pam_deny/ module, you might include the following line in your
<bf/Linux-PAM/ configuration file:
<tscreen>
<verb>
#
# add this line to your existing OTHER entries to prevent
# authentication succeeding with default applications.
#
OTHER	auth	 required	pam_deny.so
</verb>
</tscreen>

</descrip>

<sect2>Password component

<p>
<descrip>

<tag><bf>Recognized arguments:</bf></tag>

<tag><bf>Description:</bf></tag>

This component of the module denies the user the opportunity to change
their password. It always responds with <tt/PAM_AUTHTOK_ERR/ when
invoked.

<tag><bf>Examples/suggested usage:</bf></tag>

This module should be used to prevent an application from updating the
applicant user's password. For example, to prevent <tt/login/ from
automatically prompting for a new password when the old one has
expired you should include the following line in your configuration
file:
<tscreen>
<verb>
#
# add this line to your other login entries to prevent the login
# application from being able to change the user's password.
#
login	password required	pam_deny.so
</verb>
</tscreen>

</descrip>

<sect2>Session component

<p>
<descrip>

<tag><bf>Recognized arguments:</bf></tag>

<tag><bf>Description:</bf></tag>

This aspect of the module prevents an application from starting a
session on the host computer.

<tag><bf>Examples/suggested usage:</bf></tag>

Together with another session module, that displays a message of the
day perhaps (XXX - such a module needs to be written),
this module can be used to block a user from starting a shell. Given
the presence of a <tt/pam_motd/ module, we might use the following
entries in the configuration file to inform the user it is system
time:
<tscreen>
<verb>
#
# An example to see how to configure login to refuse the user a
# session (politely)
#
login	session	 required	pam_motd.so \
			file=/etc/system_time
login	session	 required	pam_deny.so
</verb>
</tscreen>

</descrip>

<!--
End of sgml insert for this module.
-->