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
NULLpointer. 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: |
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 thegetuidorgeteuiduser.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
syslograther 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.
