The Linux-PAM Module Writers' Guide

Andrew G. Morgan

Thorsten Kukuk

Version 1.0, 3. April 2008


This manual documents what a programmer needs to know in order to write a module that conforms to the Linux-PAM standard.It also discusses some security issues from the point of view of the module programmer.

Table of Contents

1. Introduction
1.1. Description
1.2. Synopsis
2. What can be expected by the module
2.1. Getting and setting PAM_ITEMs and data
2.1.1. Set module internal data
2.1.2. Get module internal data
2.1.3. Setting PAM items
2.1.4. Getting PAM items
2.1.5. Get user name
2.1.6. The conversation function
2.1.7. Set or change PAM environment variable
2.1.8. Get a PAM environment variable
2.1.9. Getting the PAM environment
2.2. Other functions provided by libpam
2.2.1. Strings describing PAM error codes
2.2.2. Request a delay on failure
3. What is expected of a module
3.1. Overview
3.1.1. Functional independence
3.1.2. Minimizing administration problems
3.1.3. Arguments supplied to the module
3.2. Authentication management
3.2.1. Service function for user authentication
3.2.2. Service function to alter credentials
3.3. Account management
3.3.1. Service function for account management
3.4. Session management
3.4.1. Service function to start session management
3.4.2. Service function to terminate session management
3.5. Authentication token management
3.5.1. Service function to alter authentication token
4. Generic optional arguments
5. Programming notes
5.1. Security issues for module creation
5.1.1. Sufficient resources
5.1.2. Who´s who?
5.1.3. Using the conversation function
5.1.4. Authentication tokens
5.2. Use of syslog(3)
5.3. Modules that require system libraries
6. An example module
7. See also
8. Author/acknowledgments
9. Copyright information for this document