pam_permission Module

Purpose

Allows or prohibits authentication through a configurable file containing a list of users and/or groups.

Description

The pam_permission module is an authentication and account-service PAM module that uses an access-control list to determine whether or not to permit or deny authentication requests. The file to use for the control list is configured via a module option and defaults to /etc/ftpusers if not specified.

If the access-control file exists, the pam_permission module will scan the file using the authenticating user name and group(s). The first match will then be used to determine the result. The general syntax for an entry in the access-control file is as follows:

[+|-][@]<name>

The optional first character controls whether to allow(+) or deny(-) the request for the user or group specified by <name>. If a '+' or '-' is not the first character in an entry, then the value of the found=<action> module option determines the behavior.

Preceding a name by the '@' symbol designates the entry as a group. Otherwise the entry is used as a user name. The first match found to a user name or group entry is used to determine access.

All spaces in an entry are ignored. Comments may be added to the file using the '#' character as the first character in the line. Only one entry or comment is allowed per line and the entries are processed one at a time, sequentially, starting at the top of the file.

Using the keyword "ALL" for <name> will match all users. Since the file is parsed sequentially, use of the "ALL" keyword should be reserved for the end of the file as any entries after it are ignored.

Upon reaching the end of the access-control file, if a match to a user name or group has not been made, the result will be the opposite value of the found=<action> module option. For example, if found=prohibit is set and the user is not found within the file, then the result for that user would be allow.

If the specified access control file does not exist, the module will return PAM_IGNORE and have no affect on the module stack. It is not recommended that the overall success or failure of the module stack depend solely on pam_permission.

It is recommended that pam_permission is used as "required" or "requisite" in conjunction with other modules. An example authentication stack is provided below to demonstrate how /etc/ftpusers behavior with the ftp service can be implemented.

#
# Provide /etc/ftpusers access-control
# to PAM-enabled ftp.
#
ftp auth requisite   /usr/lib/security/pam_permission
                              file=/etc/ftpusers  found=prohibit
ftp auth required   /usr/lib/security/pam_aix

Supported PAM module types

Authentication: Provides user authentication based on the contents of the access-control file.
Account Management: Provides account access and denial based upon the rules in the access-control file.

Options

The pam_permission module accepts the following parameters specified as options in the PAM configuration file:

Item	Description
debug	Log debugging information to syslog.
nowarn	Do not display warning messages.
file=<filename>	Use <filename> as access control file. Defaults to /etc/ftpusers.
found={allow \| prohibit}	Action if an entry match was found but is not preceded by a '+' or '-'. Default is prohibit.

Return Values

Upon successful completion PAM_SUCCESS is returned. If a failure occurs, a PAM error code will be returned, depending on the actual error.

Location

/usr/lib/security/pam_permission