LinuxDevCenter.com
oreilly.comSafari Books Online.Conferences.

advertisement


Writing PAM Modules, Part Three
Pages: 1, 2

Session

Initialise or terminate the session. This may entail tasks like writing log entries or cleaning up stored authentication tickets.



The close session function may be called by a different application than the one that opened the session, so data should be stored within the PAM system or in some non-volatile way.

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

If the module succeeds, it should return PAM_SUCCESS. If it fails, it should return PAM_SESSION_ERR.

Other Functions

The pam_strerror function returns a human-readable string of text describing the error given in the parameter.

The pam_fail_delay function is used to suggest a delay time after a failed authentication attempt. Should pam_authenticate() fail, PAM delays returning control to the application by a randomized amount of time based on the longest delay time suggested in this PAM session. The application may also recommend a delay time.

extern const char *pam_strerror(pam_handle_t *pamh, int errnum);

extern int pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec)

Response Codes

Applications need modules to return meaningful response codes.

Successes

PAM_SUCCESS
Everything went well, the module succeeded in its function, and (if appropriate) the user is who they say they are.

Failures

PAM_ABORT
Usually means the PAM handle has been corrupted.

PAM_ACCT_EXPIRED
The user's account is out of date and they may not access the system.

PAM_AUTH_ERR
Authentication error.

PAM_AUTHINFO_UNAVAIL
The module could not access the authentication information, perhaps due to hardware failure.

PAM_AUTHTOK_DISABLE_AGING
The module has had token aging disabled.

PAM_AUTHTOK_ERR
The module could not read the new authentication token.

PAM_AUTHTOK_LOCK_BUSY
The authentication token could not be changed because of a lock.

PAM_AUTHTOK_RECOVERY_ERR
The old authentication token could not be retrieved.

PAM_BAD_ITEM
A variable could not be set/deleted because it was undefined, inaccessible, or not currently set.

PAM_BUF_ERR
Memory allocation failure.

PAM_CRED_ERR
The module could not set the user's credentials.

PAM_CRED_EXPIRED
The user's credentials have expired.

PAM_CRED_INSUFFICIENT
The application is not permitted to authenticate the user, due to insufficient credentials.

PAM_CRED_UNAVAIL
The module cannot read the user's credentials.

PAM_IGNORE
The results of this module should be ignored.

PAM_MAXTRIES
The module has reached its maximum number of retries. Do not continue to attempt to authenticate this user.

PAM_NEW_AUTHTOK_REQD
The authentication token has expired, and should be renewed.

PAM_PERM_DENIED
Permission denied, or a required parameter was a NULL pointer.

PAM_SERVICE_ERR
This module cannot fulfil this type of request.

PAM_SYSTEM_ERR
Usually means an invalid PAM handle.

PAM_TRY_AGAIN
The module could not update the authentication token, therefore none of the tokens were updated.

PAM_USER_UNKNOWN
The module does not recognize the user.

Related Articles:

Writing PAM Modules, Part Two

Writing PAM Modules, Part One

Security Issues

Authentication systems need to be securely coded. There are a few concerns mentioned here, and others in the Linux-PAM Module Developer's Guide. Read both of these, and also be careful to have someone who knows secure programming check your code before you release it to production use.

  • Be careful to authenticate the correct user. The username returned by pam_get_user() is the person who will be receiving the service. This is not necessarily the same as the getuid or geteuid user.

  • When receiving an authentication token, be sure to zero the data space once you no longer need it, and certainly before you free it.

  • Ensure that the conversation response is zeroed, or otherwise has predictable content that you can test to be sure the application has returned an actual response and you're not reading junk data.

  • Use syslog rather than user messages for most errors.

  • Ensure that your module tries to fail gracefully if it runs out of system resources.

  • Be aware of the programming issues for statically-linked programs. Many modules will be statically loaded in practice.

Final Words

This is part three of a three part series on writing PAM modules. Start by writing small, useful modules that do one thing well. What do you wish your application would do when you start it?

Further Reading

Jennifer Vesperman is the author of Essential CVS. She writes for the O'Reilly Network, the Linux Documentation Project, and occasionally Linux.Com.


Return to the Linux DevCenter.




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: