The PAM API

The PAM framework, includes the PAM library ( libpam.so.1 ), which consists of an interface library and multiple authentication service modules that are the layer implementing the PAM API.

It is outside the scope of this section to detail every single API and function. However, the most commonly used and well-known APIs are presented here. The PAM API can be grouped into five functional categories:

• PAM framework functions

• Authentication functions

• Account management functions

• Session management function

• Password management functions

These functions enable an application to invoke the PAM service modules and to communicate information to these modules. The functions are described in the following sections.

PAM Framework Functions

These framework functions are PAM transaction routines for establishing and terminating a PAM session.

• pam_start() function takes, as arguments, the name of the application calling PAM, the name of the user to be authenticated, and the address of the callback conversation structure provided by the caller. It returns a handle for use with subsequent calls to the PAM library.

• pam_end() function is called to terminate the authentication transaction identified by pamh and to free any storage area allocated by the authentication module. The argument, status , is passed to the cleanup() function stored within the PAM handle, and is used to determine what module-specific state must be purged.

• pam_get_item() and pam_set_item() functions are PAM routines that enable both applications and the PAM service modules to access and update common PAM information such as service name, user name, remote host name, remote user name, and so on, from the PAM handle.

  TABLE D-1 details the items that may be manipulated by these functions. This list is exhaustive. These are manifest constants defined by the 'standard'. Others can only be added by amending the 'standard'. This would require a change to < security/pam_appl.h > and the libpam , which is the Pluggable Authentication Module library.

  Table D-1. Setting PAM Items

  Item Name	Description
  PAM_SERVICE	Service (application) name
  PAM_USER	User name
  PAM_RUSER	Remote user name
  PAM_TTY	TTY name
  PAM_RHOST	Remote host name
  PAM_CONV	pam_conv structure. (register the conversation function)
  PAM_AUTHTOK	Authenticated token
  PAM_OLDAUTHTOK	Old authentication token
  PAM_REPOSITORY	Specifies which repository is to be updated.
  PAM_USER_PROMPT	Prompt the module should use if asking for a username.

• pam_getenv() , pam_getenvlist() , and pam_putenv() functions enable applications and PAM modules to set and retrieve environment variables that are to be used for the user session.

• pam_strerror() function returns a textual representation of a PAM error, much like the strerror(3c) error.

PAM Authentication Functions

These authentication functions are used to authenticate the user and the current process. The term credentials, means whatever the PAM service module stack defines it to mean. That is each of the PAM service modules defines whatcredentials mean to them. In the case of pam_unix_cred(5) , it provides functions that establish user credential information. Among other things, pam_sm_setcred() initializes the user's privilege sets and initializes or updates the user's audit context if it hasn't already been initialized . And in the case of pam_krb5(5):

pam_sm_setcred() creates and modifies the user's credential cache. This function will initialize the user's credential cache, if it doesn't already exist, and store the initial credentials for later use by Kerberized network applications. It is important to understand that the authentication and credential setup are distinct actions. In the case of pam_krb5 , pam_sm_authenticate() performs a Kerberos authentication. pam_sm_setcred() sets up the local Kerberos ticket cache as described in kinit(1). The Kerberos credential db is later used by the GSS/Kerberos applications such as telnet and Kerberized NFS to enable single sign-on.

The following flags may be set in the flags field. They are best described by their effect on the user's credential cache.

• pam_authenticate() function called to verify the identity of the current user.

• pam_setcred() function called to set the credentials of the current process associated with the authentication handle supplied.

Typically, this process is done after the user has been authenticated (after the p am_authenticate() function succeeds).

Account Management Function

This account management function is used to validate the users account information. It typically includes checking for password and account expiration, valid login times, and etc.

• pam_acct_mgmt()

Session Management Functions

These session management functions are called on the initiation and termination of a login session.

• pam_open_session()

• pam_close_session()

The pam_unix_session module implements these calls to update the /var/adm/lastlog information. These functions can also support session auditing.

Password Management Function

This password management function is called to change the authentication token (password) associated with the user.

• pam_chauthtok()