We've expanded our Linux news coverage and improved our search! Search for all things Linux across O'Reilly!

Writing PAM-Capable Applications, Part Two

by Jennifer Vesperman
04/18/2002

PAM stands for Pluggable Authentication Modules, a system for separating authentication mechanisms from the application.

If an application is PAM-enabled, the system administrator is responsible for determining the authentication methods used, and PAM is responsible for performing the authentication. This lets the application developer concentrate on writing the main application -- and ensures that the application isn't made out-of-date solely because of an outdated authentication schema.

This is Part Two of a two-part series on writing PAM-capable applications. In Part One, we provided necessary background information and support mechanisms, and outlined the conversation mechanism which the application must provide to let the module communicate with the user.

This part covers how to call PAM authentication, account management, session management, and token-changing functions. It also covers response codes, setting credentials, and supplying a default configuration for your application.

Unless otherwise stated, the definitions for functions and types described in this article are in <security/pam_appl.h>.

pam_start()

This function initializes PAM and provides the application with a PAM handle, which is used in the rest of the functions to uniquely identify this instance of the application.

The service name parameter is the unique PAM name of the application, used in the PAM configuration files.

The username can be NULL if not known, and the module will call back later, using the conversation function, to request it.

The pam_conversation parameter is the pointer to the conversation structure. The pamh parameter is a pointer which will be filled with the PAM handle.

The function returns PAM_SUCCESS if it succeeds, and one of several failures codes if it doesn't.

pam_handle_t *pamh=NULL;
extern int pam_start(const char *service_name, const char *user,
                     const struct pam_conv *pam_conversation,
                     pam_handle_t **pamh);

Authentication

Calling this function asks PAM to call the modules' authentication methods. This authenticates the user, using the conversation function to interact with the user. If it succeeds, it returns PAM_SUCCESS. Failure is indicated with any of a number of flags.

Authentication is usually the first of the four module types to be called.

This function is usually called with the flag PAM_DISALLOW_NULL_AUTHTOK. If this flag is set and the authentication database has no stored token for the username, the authentication fails.

extern int pam_authenticate(pam_handle_t *pamh, int flags);

Account

The account management function verifies that the user account is valid, and that the user is permitted to start a session at this time. PAM account modules are available to limit accounts by time, number of users, Unix-like "nologin" blocks, and a variety of other methods.

Account is usually called after authentication, and before the session begins.

An account module will return PAM_NEW_AUTHTOK_REQD if the authentication token has expired, which allows the application to require the user to create a new authentication token. If you receive this return value, you may wish to call pam_chauthtok(), then try the account again.

It returns PAM_SUCCESS if the account is valid, and any of a number of flags to indicate failure.

extern int pam_acct_mgmt(pam_handle_t *pamh, int flags);

Pages: 1, 2

Next Page