Security Guide

Pluggable Authentication Module

The pluggable authentication module (PAM) framework provides system administrators with the ability to incorporate multiple authentication mechanisms into an existing system through the use of pluggable modules. Applications enabled to make use of PAM can be plugged-in to new technologies without modifying the existing applications. This flexibility allows administrators to do the following:

Select any authentication service on the system for an application
Use multiple authentication mechanisms for a given service
Add new authentication service modules without modifying existing applications
Use a previously entered password for authentication with multiple modules

The PAM framework consists of a library, pluggable modules, and a configuration file. The PAM library implements the PAM application programming interface (API) and serves to manage PAM transactions and invoke the PAM service programming interface (SPI) defined in the pluggable modules. Pluggable modules are dynamically loaded by the library based on the invoking service and its entry in the configuration file. Success is determined not only by the pluggable module but also by the behavior defined for the service. Through the concept of stacking, a service can be configured to authenticate through multiple authentication methods. If supported, modules can also be configured to use a previously submitted password rather than prompting for additional input.

The following illustration shows the interaction between applications, PAM library, configuration file, and PAM modules. The fictitious PAM applications (pam_login, pam_su, and pam_passwd) invoke the PAM API in the PAM library. The library determines the appropriate module to load based on the application entry in the configuration file and calls the PAM SPI in the module. Communication occurs between the PAM module and the library through the use of a conversation function implemented in the PAM module. Success or failure from the module and the behavior defined in the configuration file then determine if another module needs to be loaded. If so, the process continues; otherwise, the data is passed back to the application.

Figure 3. PAM Framework and Entities. This illustration shows how fictitious application commands use the PAM library to access the appropriate PAM module.

PAM Library

The PAM library, /usr/lib/libpam.a, contains the PAM-API that serves as a common interface to all PAM applications and also controls module loading. Modules are loaded by the PAM library based on the stacking behavior defined in the /etc/pam.conf file.

The following PAM API functions invoke the corresponding PAM SPI provided by a PAM module. For example, the pam_authenticate API invokes the pam_sm_authenticate SPI in a PAM module.

pam_authenticate
pam_setcred
pam_acct_mgmt
pam_open_session
pam_close_session
pam_chauthtok

Also provided in the PAM library are several functions that enable an application to invoke PAM modules and also to pass information to PAM modules. The following PAM framework APIs are implemented in AIX:

pam_start	Establish a PAM session
pam_end	Terminate a PAM session
pam_get_data	Retrieve module-specific data
pam_set_data	Set module-specific data
pam_get_item	Retrieve common PAM information
pam_set_item	Set common PAM information
pam_get_user	Retrieve user name
pam_strerror	Get PAM standard error message

PAM Modules

PAM modules allow multiple authentication mechanisms to be used collectively or independently on a system. A given PAM module must implement at least one of four module types. The module types are described as follows, along with the corresponding PAM SPIs that are required to conform to the module type.

Authentication Modules

Authenticate users and set, refresh, or destroy credentials. These modules identify user based on their authentication and credentials.

Authentication module functions:

pam_sm_authenticate
pam_sm_setcred

Account Management Modules

Determine validity of the user account and subsequent access after identification from authentication module. Checks performed by these modules typically include account expiration and password restrictions.

Account management module function:

pam_sm_acct_mgmt

Session Management Modules

Initiate and terminate user sessions. Additionally, support for session auditing may be provided.

Session management module functions:

pam_sm_open_session
pam_sm_close_session

Password Management Modules

Perform password modification and related attribute management.

Password management module functions:

pam_sm_chauthtok

PAM Configuration File

The /etc/pam.conf configuration file consists of service entries for each PAM module type and serves to route services through a defined module path. Entries in the file are composed of the following whitespace-delimited fields:

service_name module_type control_flag module_path module_options

Where:

`service_name`	Specifies the name of the service. The keyword OTHER is used to define the default module to use for applications not specified in an entry.
`module_type`	Specifies the module type for the service. Valid module types are auth, account, session, or password.
`control_flag`	Specifies the stacking behavior for the module. Supported control flags are required, sufficient, or optional.
`module_path`	Specifies the path name to a library object that implements the service functionality. Entries for `module_path` should start from the root (/) directory. If the entry does not begin with /, then /usr/lib/security will be prepended to the file name.
`module_options`	Specifies a list of options that can be passed to the service modules. Values for this field are dependent on the options supported by the module defined in the `module_path` field.

All fields defined above are required for each entry except for the module_options field, which is optional. Malformed entries or entries with invalid values for the module_type or control_flag fields are ignored by the PAM library. Entries beginning with a number sign (#) character at the beginning of the line are also ignored because this denotes a comment.

Stacking is implemented in the configuration file by creating multiple entries with the same module_type field. The modules are invoked in the order in which they are listed in the file, with the final result determined by the control_flag field specified for each entry. Valid values for the control_flag field and the corresponding behavior in the stack are as follows:

required	All required modules in a stack must pass for a successful result. If one or more of the required modules fail, all of the required modules in the stack will be attempted, but the error from the first failed required module is returned.
sufficient	If a module flagged as sufficient succeeds and no previous required or sufficient modules have failed, 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 for the service must succeed. If another module in the stack is successful, a failure in an optional module is ignored.

The following is an example /etc/pam.conf file that could be used on a system that has additional PAM modules installed:

#
# PAM configuration file /etc/pam.conf
#

# Authentication Management
login   auth     required       /usr/lib/security/pam_aix
login   auth     required       /usr/lib/security/pam_verify
login   auth     optional       /usr/lib/security/pam_test      use_first_pass
su      auth     sufficient     /usr/lib/security/pam_aix
su      auth     required       /usr/lib/security/pam_verify
OTHER   auth     required       /usr/lib/security/pam_aix

# Account Management
OTHER   account  required       /usr/lib/security/pam_aix

# Session Management
OTHER   session  required       /usr/lib/security/pam_aix

# Password Management
OTHER   password required       /usr/lib/security/pam_aix

The example configuration file contains three entries for the login service. Having specified both pam_aix and pam_verify as required, the user must enter two passwords to be authenticated, and both passwords must succeed for the user to be authenticated. The third entry for the pam_test module is optional and its success or failure will not affect whether the user is able to login. The option use_first_pass to the pam_test module allows a previously entered password to be used instead of prompting for a new one.

The su command behaves such that if pam_aix succeeds, authentication succeeds. If pam_aix fails, then pam_verify must pass for successful authentication.

Use of the OTHER keyword as a service name enables a default to be set for any other services that are not explicitly declared in the configuration file. Setting up a default ensures that all cases for a given module type will be covered by at least one module.

Adding a PAM Module

To add a PAM module, use the following procedure:

Install the module in the /usr/lib/security directory.
Set file ownership to root and permissions to 555. The PAM library does not load any module not owned by the root user.
Update the /etc/pam.conf configuration file to include the module in entries for the desired service names.
Test the affected services to ensure their functionality. Do not log off the system until a login test has been performed.

Changing the /etc/pam.conf

When changing the /etc/pam.conf configuration file, consider the following:

AIX does not provide a default /etc/pam.conf file, so the file must be created before using PAM. When creating the file, set the file ownership to root and base permissions to 644. The file can then be manually edited by the root user to make the desired changes.
Determine the default module to use for each module type and then make use of the OTHER keyword to prevent specifying the module for each service.
Read any documentation supplied for a chosen module, and determine which control flags and options are supported and what their impact will be.
Select the ordering of modules and control flags carefully, keeping in mind the behavior of required, sufficient, and optional control flags in stacked modules.

Note

Incorrect configuration of the PAM configuration file can result in a system that cannot be logged in to. After making changes to the file, always test the affected applications before logging out of the system. A system that cannot be logged in to can be recovered by booting the system in maintenance mode and correcting the /etc/pam.conf configuration file.

Enabling PAM Debug

The PAM library can provide debug information during execution. After enabling the system to collect debug output, the information gathered can be used to track PAM-API invocations and determine failure points in the current PAM setup. To enable PAM debug output, follow these steps:

Create an empty file at /etc/pam_debug. The PAM library checks for existence of the /etc/pam_debug file and if found, enables syslog output.
Edit the /etc/syslog.conf file to contain the appropriate entries for the desired levels of messages.
Restart the syslogd daemon so that configuration changes are recognized.
When the PAM application is restarted, debug messages will be collected in the output file defined in the /etc/syslog.conf configuration file.

Integrating PAM in AIX

The integration of PAM in AIX is accomplished through the use of an AIX loadable authentication module, PAM, and a pam_aix module. These modules provide the following independent paths of PAM integration:

Access is provided from AIX security services to PAM by means of the PAM module
Access is provided from a PAM application to AIX security services through the PAM module (pam_aix)

PAM Module

AIX security services can be configured to call PAM modules through the use of the existing AIX loadable authentication module framework. When the /usr/lib/security/methods.cfg file is set up correctly, the simple load module PAM will route AIX security services (passwd, login, and so on) to the PAM library. The PAM library will check the /etc/pam.conf file to determine which PAM module to use and then make the corresponding PAM SPI call. Return values from PAM are mapped to AIX error codes and returned to the calling program.

Figure 4. AIX Security Service to PAM Module Path. This illustration shows the path an AIX security service call will take when PAM is properly configured. The PAM modules shown (pam_krb, pam_ldap, and pam_dce) are listed as examples of third party solutions.

PAM is a simple load module that is installed in the /usr/lib/security directory and is an authentication only module. The PAM module must be combined with a database to form a compound load module. The following example shows the stanzas that could be added to the methods.cfg file to form a compound PAM module with a database called files. The BUILTIN keyword for the db attribute will designate the database as UNIX files.

PAM:
        program = /usr/lib/security/PAM

PAMfiles:
        options = auth=PAM,db=BUILTIN

Creating and modifying users is then performed by using the -R option with the administration commands and by setting the SYSTEM attribute when a user is created.

mkuser -R PAMfiles SYSTEM=PAMfiles registry=PAMfiles pamuser

This act will inform further calls to AIX security services (login, passwd, and so on) to use the PAM load module for authentication. While the files database was used for the compound module in this example, other databases, like LDAP, can also be used if they are installed. Creating users as previously described will result in the following mapping of AIX security to PAM API calls:

         AIX                     PAM API
        =====                   =========
        authenticate       -->  pam_authenticate
        chpass             -->  pam_chauthtok
        passwdexpired      -->  pam_acct_mgmt
        passwdrestrictions -->  No comparable mapping exists, success returned

Customizing the /etc/pam.conf file allows the PAM API calls to be directed to the desired PAM module for authentication. Stacking can be implemented in order to further refine the authentication mechanism.

Data prompted for by an AIX security service is passed to PAM through the pam_set_item function because it is not possible to accommodate user dialog from PAM. PAM modules written for integration with the PAM module should retrieve all data with pam_get_item calls and should not attempt to prompt the user to input data as this is handled by the security service.

Loop detection is provided to catch possible misconfiguration in which an AIX security service is routed to PAM and then a PAM module in turn attempts to call the AIX security service to perform the operation. Detection of this loop event will result in an immediate failure of the intended operation.

Note

The /etc/pam.conf file should NOT be written to make use of the pam_aix module when using PAM integration from an AIX security service to a PAM module as this will result in a loop condition.

pam_aix Module

The pam_aix module is a PAM module that provides PAM-enabled applications access to AIX security services by providing interfaces that call the equivalent AIX services where they exist. These services are in turn performed by a loadable authentication module or AIX builtin function based on the users definition and the corresponding setup in methods.cfg. Any error codes generated during execution of an AIX service are mapped to the corresponding PAM error code.

Figure 5. PAM Application to AIX Security Subsystem Path. This illustration shows the path a PAM application API call will follow if the /etc/pam.conf file is configured to make use of the pam_aix module. As shown in the diagram, the integration allows users to be authenticated by any of the loadable authentication modules (DCE, LDAP, or KRB5) or in UNIX files (compat).

The pam_aix module is installed in the /usr/lib/security directory. Integration of the pam_aix module requires that the /etc/pam.conf file be configured to make use of the module. Note that stacking is still available but chosen not to be shown in the following simple example of the /etc/pam.conf file:

#
# Authentication management
#
OTHER   auth     required       /usr/lib/security/pam_aix

#
# Account management
#
OTHER   account  required       /usr/lib/security/pam_aix 

#
# Session management
#
OTHER   session  required       /usr/lib/security/pam_aix 

#
# Password management
#
OTHER   password required       /usr/lib/security/pam_aix

The pam_aix module has implementations for the pam_sm_authenticate, pam_sm_chauthok and pam_sm_acct_mgmt SPI functions. The pam_sm_setcred, pam_sm_open_session, and pam_sm_close_sessionSPI are also implemented in the pam_aix module, but these SPI simply return PAM_SUCCESS invocations.

The following is a rough mapping of PAM SPI calls to the AIX security subsystem:

         PAM SPI                    AIX
        =========                  =====
        pam_sm_authenticate   -->  authenticate
        pam_sm_chauthtok      -->  passwdexpired, chpass
                                   Note: passwdexpired is only checked if the
                                   PAM_CHANGE_EXPIRED_AUTHTOK flag is passed in.
        pam_sm_acct_mgmt      -->  loginrestrictions, passwdexpired
        pam_sm_setcred        -->  No comparable mapping exists, PAM_SUCCESS returned
        pam_sm_open_session   -->  No comparable mapping exists, PAM_SUCCESS returned
        pam_sm_close_session  -->  No comparable mapping exists, PAM_SUCCESS returned

Data intended to be passed to the AIX security subsystem may either be set using the pam_set_item function prior to module use or the pam_aix module will prompt for data if it does not already exist.