LinuxDevCenter.com
oreilly.comSafari Books Online.Conferences.

advertisement


Writing PAM Modules, Part Three

by Jennifer Vesperman
05/30/2002

PAM stands for Pluggable Authentication Modules and is a system for providing application independence for authentication. A PAM-enabled application calls a stack of PAM modules to run authentication, open and close sessions, and check account validity.

This is part three of a three-part series on writing PAM modules. Part one discussed the background information needed to write modules. Part two covered supporting code, including the conversation structure.

PAM modules are grouped into four module types, though there are six critical functions. Applications call each of the functions as they need them, but system administrators can only choose functions by their module type.

Required Functions

An application needs to completely fulfil the requirements for at least one of the module types. It should, but is not required to, respond to a request for the other module types with PAM_SERVICE_ERR or PAM_IGNORE.

The four types are: account, authentication, password, and session.

All of these functions have a flag parameter. The PAM_SILENT flag is valid for any function, and tells the module not to pass any text errors or warnings to the application. Flags may be logically ORed together.

Account

This module type establishes whether the user can gain access at this time. The module should assume that the user has previously been authenticated. The module may verify whether or not a password has expired, and may return PAM_NEW_AUTHTOK_REQD if it has.

The flag PAM_DISALLOW_NULL_AUTHTOK tells the module to check whether or not there is a NULL authentication token in the token database. If so, return PAM_AUTH_ERR.

PAM_EXTERN int pam_sm_acct_mgmt(pam_handle_t *pamh, int flags, int argc, const char **argv);

If the module succeeds, it should return PAM_SUCCESS. Other valid responses are:

  • PAM_ACCT_EXPIRED
  • PAM_AUTH_ERR
  • PAM_NEW_AUTHTOK_REQD
  • PAM_USER_UNKNOWN

Authentication

User Validation

The first part of an authentication module is the actual user validation.

The flag PAM_DISALLOW_NULL_AUTHTOK tells the module to check whether or not there is a NULL authentication token in the token database. If so, return PAM_AUTH_ERR. Without this flag, the module can return PAM_SUCCESS in these cases without prompting the user for a token.

PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags, int argc, const char **argv);

If the module succeeds, it should return PAM_SUCCESS. Other valid responses are:

  • PAM_AUTH_ERR
  • PAM_AUTHINFO_UNAVAIL
  • PAM_CRED_INSUFFICIENT
  • PAM_MAXTRIES
  • PAM_USER_UNKNOWN

Credential Setting

The second part of authentication is setting the user's credentials. Such credentials may be a Kerberos ticket, or Unix group membership. Only set credentials that are appropriate to the module you're writing.

Valid flags:

PAM_DELETE_CRED
Delete the credentials associated with this authentication system.

PAM_ESTABLISH_CRED
Set the credentials associated with this authentication system.

PAM_REFRESH_CRED
Extend the credentials' life.

PAM_REINITIALIZE_CRED
Reinitialize the credentials for this authentication system.

PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int argc, const char **argv);

Related Reading

Learning the Korn Shell
By Bill Rosenblatt, Arnold Robbins

If the module succeeds, it should return PAM_SUCCESS. Other valid responses are:

  • PAM_CRED_ERR
  • PAM_CRED_EXPIRED
  • PAM_CRED_UNAVAIL
  • PAM_USER_UNKNOWN

Password

This module type sets or resets the authentication token. Linux-PAM calls the module twice, once to verify that everything is ready and once to change the token itself.

Valid flags:

PAM_CHANGE_EXPIRED_AUTHTOK
User's authentication token should only be changed if it has expired.

PAM_PRELIM_CHECK
This verifies that the module is being asked for a readiness status, to ensure that the module is currently capable of updating the user's authentication token. If not, the module should return PAM_TRY_AGAIN.

PAM_UPDATE_AUTHTOK
The module should actually change the authentication token.

PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int argc, const char **argv);

If the module succeeds, it should return PAM_SUCCESS. Other valid responses are:

  • PAM_AUTHTOK_DISABLE_AGING
  • PAM_AUTHTOK_ERR
  • PAM_AUTHTOK_LOCK_BUSY
  • PAM_AUTHTOK_RECOVERY_ERR
  • PAM_PERM_DENIED
  • PAM_TRY_AGAIN
  • PAM_USER_UNKNOWN

Pages: 1, 2

Next Pagearrow




Linux Online Certification

Linux/Unix System Administration Certificate Series
Linux/Unix System Administration Certificate Series — This course series targets both beginning and intermediate Linux/Unix users who want to acquire advanced system administration skills, and to back those skills up with a Certificate from the University of Illinois Office of Continuing Education.

Enroll today!


Linux Resources
  • Linux Online
  • The Linux FAQ
  • linux.java.net
  • Linux Kernel Archives
  • Kernel Traffic
  • DistroWatch.com


  • Sponsored by: