OS: Debian “Woody” with 2.4 kernel (Linux-PAM will be installed by default)
Docs: install “libpam-doc 0.72-35” from CD-4 “unofficial extras”

PAM (“Pluggable Authentication Modules”) is a set of library modules that an application may
use for user authentication.
If it does, such an application is said to be “PAM-aware” and to offer “a restrictive service”.
(Use the “ldd” command to check if an application is “PAM-aware”.)
PAM was originally developed by SUN Microsystems.
It offers the big advantage of being able to dynamically switch between authentication methods
without having to rewrite the PAM-aware application.

The library modules (dynamically loadable object files) reside in /lib/security.
(On some Linux platforms: /usr/lib/security)
Some of these modules need special files which usually reside in /etc/security.
These files should be provided by default, but may contain commentary lines only.
They all have a specific format and may be modified by the superuser.
Modules may be able to log information via syslogd, so you may wish to edit /etc/syslog.conf
(Hint: check if basic logging of authentication has already been set to: /var/log/auth.log)

The behavior of “restrictive/PAM-aware” services is managed via the PAM configuration file(s).
Originally PAM used one configuration file (/etc/pam.conf) that contained lines (so-called “rules”)
of a specific 5-fields-format: service module-type control-flag module-path argument(s).
Nowadays PAM uses a special directory (/etc/pam.d) which contains one configuration file
per “restrictive service”.
As file name=service name, the lines in these files are of the following 4-fields-format:
module-type control-flag module-path argument(s)

The directory also contains a special file (/etc/pam.d/other).
This file is used by all restrictive services that haven't got a proper config file of their own.
It usually specifies a default authentication method (like basic Unix-authentication),
but could/should be made more restrictive if necessary.

Directory-based PAM configuration offers many advantages:
- quicker to parse
- easier to maintain (no risk to affect behavior of another “service”)
- access permissions per file allow f.i. limitation of “read” access per file
- possibility to link config files to a single file

Note:
On most Linux platforms, PAM will be compiled to support just one config file method.
This means that if both /etc/pam.conf and /etc/pam.d/* exist,
/etc/pam.conf will be ignored and the config files in /etc/pam.d will be used.
In the absence of /etc/pam.d, /etc/pam.conf will be used.
However, on some Linux platforms, PAM will be compliled to support both config file methods.
In that case, “rules” in /etc/pam.d override those in /etc/pam.conf

First of all: file name=service name; must be in lower case.
The use of “#” (for commentary) and of “\ <return>” is allowed.
Each line (“rule”) consists of 4 fields separated by white space:

Example: auth required pam_rootok.so debug
User must be superuser ('required'), if not: authentication fails; 'debug' will log via syslogd

- auth: handles the authentication process (asks for and checks password)
- account: checks if authentication is allowed at all (checks if account hasn't expired)
- password: handles setting/changing of passwords (checks if requirements have been met)
- session: handles use of account after successful authentication (uses /etc/passwd)

Correct path name to the compiled library module's file.
The compiled library modules are located in /lib/security (or /usr/lib/security).
Relative path names may be supported.

A space separated list of module-specific arguments, usually in lower case.
May include 'debug' or 'audit' to indicate logging level.

Note:
Modules may be “stacked”, i.e. a config file may start by 3 or 4 “auth”-module lines.
In that case the correct order of lines and the correct use of control flags are very important!
(see: 'su' examples in part 3 of this document)

If you want to experiment with these examples: first of all, move 'su' to 'su.org'
and create your own 'su'-file!
Next, check 'su' behavior for 3 types of user:
the root-user, a user who is a “wheel/root-group” member and a normal user.
Hint: take a good look at the logfile(s)!

Ex.1: Enable normal 'su' for root; block 'su' for all other users

If you are the root-user, this will succeed: you may still 'su' without providing a password.
If you are NOT the root-user, this will fail and you'll get “su: Permission denied”.
Note: if this is the only line in the file, there's no difference in 'su' behavior if the control
flag is set to 'required'!

Ex.2: Enable normal 'su' for root and for all other users

If you are the root-user, line 1 will succeed and because of the 'sufficient' flag, line 2
won't be invoked at all. The root-user will be able to 'su' without providing a password.
If you are NOT the root-user, line 1 will fail, but because of the 'sufficient' flag, line 2
will be invoked.
Line 2 will allow all non-root users to 'su', but they MUST provide a correct PASSWORD.
Note:
If the control flag in the first line is set to 'required', this will make a lot of difference!
For the root-user this means that he will need to provide a PASSWORD any time he uses 'su'!
This bit of authentication is handled by line 2. Then, both requirements will have been met.
For non-root-users, line 1 will still fail, but line 2 will be executed nevertheless
(user will get “Password:” prompt).
Even so, if one of the 'required' steps for a certain type of authentication fails, the summarized
PAM report on that type of authentication will still be “FAIL”!
So access to 'su' will be blocked to any non-root-user!!

Ex.3: Enable normal 'su' for root PLUS 'su' to root-account for all “wheel-group” members

The pam_wheel.so module handles access to the root-account.
(It is NOT APPLICABLE if access to non-root accounts must be handled!)
Access is based on membership of the “wheel-group” in /etc/group.
(It is NOT based on the login-group in /etc/passwd!)
If there's no “wheel-group”, the “root-group” (GID=0) is the default.
Note: add “group=groupname” to restrict access to another group than the “wheel-group”.

For “wheel-group” members, line 1 will fail, but line 2 will succeed.
The 'trust' argument will allow them to 'su' to the root-account without providing a password.
They won't be allowed to 'su' to any other account though (no authentication provided for that!).
Due to this configuration, other users can't use 'su' at all (no authentication provided for them!).
Note: don't leave out 'trust', for non-trusted access requires a password and that can't
be handled by pam_wheel.so! Solution: compare Ex.4 to ex.5!!

Ex.4: Is this a safe one??

Line 1 will offer normal 'su' behavior to the root-user.
If a “wheel-group” member wants to 'su' to the root-account, line 1 will fail,
but line 2 will succeed. Because there is no 'trust' argument, he will have to provide
a correct root-PASSWORD! This can only be handled if line 3 is present!
If a “wheel-group” member wants to 'su' to a non-root-user account, line 1 will fail
and line 2 won't be applicable. Access will then be handled by line 3, which means he
will have to provide a PASSWORD!
In short, this will allow “wheel-group” members access to ALL accounts if they
know the password!
For all other users: if they want to 'su' to the root-account, both lines 1 and 2 will fail,
but because of the 'sufficient' flags, line 3 will still be invoked and allow them access
if they know the root-PASSWORD.
Equally they will gain access to all other accounts via line 3 (line 1 will fail, line 2 won't
be applicable).

Ex.5: This might be better!

The 'required' flag in line 2 blocks access to the root-account to non-wheel-members.
This 'su' configuration offers normal 'su' behavior to the root user.
“wheel-group” members will be allowed to 'su' to ALL accounts including the
root-account, if they know the PASSWORD.
Other users will be allowed to 'su' to accounts of other users if they know the PASSWORD
(line 1 will fail, line 2 won't be applicable, line 3 will handle access).
Access to the root-account is blocked to them as they can't meet the requirement in line 2
(they will get a “Password:” prompt, but the summarized authentication report will be: FAIL).

Copyright (C) 2002 Integrated Services; tux4u.nl
Author: Drs.M.Waldorp-Bonk
pam_mini-howto.html 20021113