http://www.ibm.com/developerworks/linux/library/l-pam/index.

html

English Sign in (or register)

Technical topics Evaluation software Community Events

The basic Pluggable Authentication Module and how to configure it and write a login app

Vishal Srivistava (vissriva@in.ibm.com), Associate Software Engineer, IBM

Summary: The Pluggable Authentication Module (PAM) API exposes a set of functions that application programmers use for security-related
functions like user authentication, data encryption, LDAP, and more. In this article, get a basic guide to the PAM model on Linux, see how to
configure PAM, and learn how to design a sample PAM login application in 10 easy steps.

Date: 10 Mar 2009

Level: Introductory
Also available in: Russian Japanese Portuguese

Activity: 41851 views

Comments: 0 (View | Add comment - Sign in)

Average rating (28 votes)

Rate this article

For Linux users, sharing files securely is a cumbersome task. For example, needing to recall multiple passwords is taxing, and redesigning system
access applications (like login, su, password, ftp, etc.) is time-consuming. Adding to the difficulty is the process of authentication, where a system
identifies a user and provides deserved access control to that user.

A history of PAM's usage

PAM is an API that takes care of authenticating a user to a service. Before PAM, applications like login (and rlogin, telnet, rsh) looked for the
username in /etc/passwd, then compared the two and authenticated the user-typed name. All applications used these shared services, although the
implementation details and authority to configure them was not shared.

Next, application developers tried coding their own processes. With this came the need to separate the application and security module (a common
security module can be shared by applications and can be configured as needed).

The PAM mechanism integrates multiple low-level authentication schemes into a high-level API that allows programs that rely on authentication
to be written independently of the underlying authentication scheme. The principal feature of PAM is the dynamic configuration of authentication
through either an /etc/pam.d or /etc/pam.conf file.

PAM can be configured to deny certain programs the right to authenticate users and to warn when certain programs attempt to authenticate. PAM
programs make use of PAM modules (authentication modules): They are attached to applications at runtime in order to work.

Figure 1 shows the basic flow of the PAM model.

Figure 1. PAM library parses the config file and loads modules to it

What operating systems support PAM?

PAM was first developed by Sun Microsystems in 1995 and is supported by the following operating system versions (and higher):

RedHat 5.0
SUSE 6.2
Debian 2.2
Mandrake 5.2
 http://www.ibm.com/developerworks/linux/library/l-pam/index.html

Caldera 1.3
TurboLinux 3.6

PAM is also supported by recent versions of Solaris™, AIX®, HP-UX, and Mac OS® X. PAM was later standardized as a part of X/Open UNIX®
standardization process (in the X/Open single sign-on service (XSSO) architecture).

What kind of PAM can I get?

Though they are not strictly classified, you could say there are three kinds of PAM:

1. Linux-PAM: Linux-PAM covers all of the PAM discussed in this article. The main architecture of PAM on any of the Linux platforms is
similar to the Linux-PAM version.
2. OpenPAM: OpenPAM is another implementation of PAM developed by Dag-Erling Smorgrav at NAI labs as part of DARPA-CHATS
research program. Because it is open source, it is mainly used by FreeBSD, NetBSD, and applications (plus Mac OS X).
3. Java™ PAM or JPam: PAM is basically a standard authentication module supporting Linux and UNIX. JPam acts as a bridge between the
Java part and the usual PAM. JPam enables the use of PAM modules or facilities (like auth, account, passwd, session, etc.) by Java-based
applications. It features JAAS and direct APIs and support for most Unix OS and architectures.

Although these are different PAMs, their primary functionality remains the same.

What are PAM modules like?

Installing PAM is a step-by-step process. See Resources for installation instructions.

PAM modules are classified into module type. Any given module should implement at least one of the four module type functions:

1. The authentication module is used to authenticate users or set/destroy credentials.

2. The account management modules perform actions related to access, account and credential expiration, password restrictions/rules, etc.
3. The session management module is used for initializing and terminating sessions.
4. The password management module performs actions related to password change/updates.

PAM provides different functional capabilities, such as single sign-on authentication, access control, and more. The implementation of each are
handled by different modules. Here are some of the major modules:

pam_access delivers log-daemon-style login access control using login/domain names depending on pre-defined rules in /etc/security
/access.conf.
pam_cracklib checks the passwords against the password rules.
pam_env sets/unsets environment variables from /etc/security/pam_env_conf.
pam_debug debugs PAM.
pam_deny locks out PAM modules.
pam_echo prints messages.
pam_exec executes an external command.
pam_ftp is the module for anonymous access.
pam_localuser requires the user to be listed in /etc/passwd.
pam_unix provides traditional password authentication from /etc/passwd.

There are many other modules (pam_userdb, pam_warn, pam_xauth), which take a set of values which they return. (Details of these modules can
be found in the PAM administration guide in Resources.)

Configuring PAM

PAM configuration is generally implemented in the configuration file residing in /etc/pam.d or /etc/pam.conf (for old versions).

The configuration file structure

For each service that uses PAM, there is a corresponding file in the directory, which contains the rules or instructions for how authentication and
account information should be obtained for that service. There is usually one rule per line.

Fields in the PAM configuration files include:

Service_name specifies the name of the service/application. (The default is OTHER.)

Module_type specifies module type (auth/account/session/passwd) for the corresponding service in Service_name field.
Control_flag specifies the stacking behavior of the module. It can take such values as requisite, required, sufficient, and optional.
Module_path specifies the path name to the library object which implements the module. It is set to /lib/security by default.
Module_options/module_args (optional fields) specify the options or arguments that can be passed to the services modules.
 http://www.ibm.com/developerworks/linux/library/l-pam/index.html

The modules are invoked in the order in which they are listed in the configuration file, depending on what the Control_flag for each entry allows.
Control_flag values include:

Required: All required modules in a stack must pass for a successful result. If one or more of the required module fails, all of the required
modules in the stack are implemented, but the first error is returned.
Sufficient: If a module flagged as sufficient succeeds and no previous required or sufficient modules have failed, then all remaining modules
in the stack are ignored and success is returned.
Optional: If none of the modules in the stack are required and no sufficient modules have succeeded, then at least one optional module of the
service/application must succeed.

Examples of PAM config files

Table 1 shows some examples of PAM configuration files on various operating systems.

Table 1. A world of PAM configuration files

System Found in ... Type Control_flag Module
Red Hat /etc/pam.d auth required /lib/security/pam_unix.so
Red Hat /etc/pam.d account sufficient /lib/security/pam_unix.so
Red Hat /etc/pam.d session required /lib/security/pam_limit.so
AIX /etc/pam.conf auth required /usr/lib/security/pam_aix
AIX /etc/pam.conf account required /usr/lib/security/pam_aix
AIX /etc/pam.conf password required /usr/lib/security/pam_aix
zSUSE 64-bit | 32-bit /etc/pam.conf auth required /lib64/security/pam_unix.so | /lib/security/pam_unix.so
zSUSE 64-bit | 32-bit /etc/pam.conf account required /lib64/security/pam_unix.so | /lib/security/pam_unix.so
zSUSE 64-bit | 32-bit /etc/pam.conf session required /lib64/security/pam_unix.so | /lib/security/pam_unix.so
Solaris /etc/pam.conf auth required /usr/lib/security/pam_unix.so.1
Solaris /etc/pam.conf account required /usr/lib/security/pam_unix.so.1
Solaris /etc/pam.conf password required /usr/lib/security/pam_unix.so.1
HP-UX /etc/pam.conf auth required libpam_unix.so.1
HP-UX /etc/pam.conf account required libpam_unix.so.1
HP-UX /etc/pam.conf password required libpam_unix.so.1

The PAM "other" file

The default PAM configuration file /etc/pam.d is used for all other services that are not explicitly configured and is perhaps the simplest and
most robust default file upon which PAM relies. The internals look something like this:

/etc/pam.d/other File

auth required pam_warn.so

auth required pam_deny.so
account required pam_warn.so
account required pam_deny.so
password required pam_warn.so
password required pam_deny.so
session required pam_warn.so
session required pam_deny.so

This file is very simple. For all module types, the Control_flag is the same: required. Two modules are called:

1. First, pam_warn.so is called to log information about the attempt in progress.

2. Then pam_deny.so is called to simply return a failure and prevent any kind of connection or authentication from taking place.

Therefore, any service that uses PAM must be explicitly configured to allow authentication; otherwise, attempts will fail.

10 steps to designing a simple PAM login app

These 10 steps can help you implement your own PAM application and help you understand the workings of a PAM session:

1. Include header files for the PAM implementation (for example, pam_appl.h, pam_misc.h).
2. In the main function, initialize the PAM library libpam.so (which loads the modules specified in the configuration file for application) using
a unique handle.
3. Attempt authentication for all modules and handle failure scenarios.
4. Check for user credential and account details.
5. Open a new PAM session.
 http://www.ibm.com/developerworks/linux/library/l-pam/index.html

6. Set the environment for the user using credentials.

7. When the user is done, unset the user environment.
8. Close the PAM session.
9. Exit from the library libpam.so with the handle value.
10. EXIT.

In conclusion

Relying on PAM to help wrangle low-level authentication efforts into a more manageable whole is a sound move to simplifying this security
mechanism. In this article, you've learned:

The basic PAM architecture

How to configure PAM modules
An outline of a PAM login app as a guide for understanding how they work

Now you can move onto the more advanced topics in using PAM modules—starting with the Resources below..

Resources

Learn

The Linux-PAM guides offer documentation on systems administration issues, module writing, and application development.

Here's the view of PAM from the SUSE Linux Unofficial FAQ.

And if you need to upgrade, Gentoo has a Linux-PAM upgrade guide.

Take a look at the X/Open Single Sign-on Service (XSSO) architecture model.

Ready for more advanced topics in using PAM?

"A comparison of security subsystems on AIX, Linux, and Solaris" (developerWorks, October 2005): How PAM works in each.
"Applying mount namespaces" (developerWorks, September 2007): View the relevant part of a PAM module.
"Centralize user accounts with OpenLDAP" (developerWorks, May 2006): See how PAM on Linux cooperates with LDAP.
"Improve security with polyinstantiation" (developerWorks, February 2008): Using a Pluggable Authentication Module to protect
private data.
"LPI exam 202 prep, Topic 210: Network client management" (developerWorks, May 2006): Configure PAM to support
authentication.
"PAM configuration on SUSE Enterprise Linux 9" (Technote (IBM Tivoli Netcool/OMNIbus), October 2008): How to configure the
PAM module for ObjectServer authentication with local system users.

In the developerWorks Linux zone, find more resources for Linux developers (including developers who are new to Linux), and scan our
most popular articles and tutorials.

See all Linux tips and Linux tutorials on developerWorks.

Stay current with developerWorks technical events and Webcasts.

Get products and technologies

With IBM trial software, available for download directly from developerWorks, build your next development project on Linux.

Discuss

Get involved in the developerWorks community through blogs, forums, podcasts, and spaces.

About the author

Vishal Srivistava has worked with the many flavors of UNIX and Linux at the core level. Since June 2007, Srivistava has been with IBM India
Software Labs and is currently a part of team responsible for the development of the core engine of IBM IIS. This position has given him lots of
experience in configuring the team application to use PAM on a multitude of UNIX platforms.
 http://www.ibm.com/developerworks/linux/library/l-pam/index.html

Close [x]

IBM ID:
Need an IBM ID?
Forgot your IBM ID?

Password:
Forgot your password?
Change your password

Keep me signed in.

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. Select information in your developerWorks profile is displayed to the
public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will
accompany the content that you post.

All information submitted is secure.

Close [x]

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies
the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be
your email address for privacy reasons.

Display name: (Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

Average rating (28 votes)

1 star 1 star
2 stars 2 stars
3 stars 3 stars
4 stars 4 stars
5 stars 5 stars

Add comment:

Sign in or register to leave a comment.

Note: HTML elements are not supported within comments.

 http://www.ibm.com/developerworks/linux/library/l-pam/index.html

Notify me when a comment is added1000 characters left

Be the first to add a comment

Print this page Share this page Follow developerWorks

About Feeds and apps Report abuse Faculty

Help Newsletters Terms of use Students
Contact us IBM privacy Business Partners
Submit content IBM accessibility