oreilly.comSafari Books Online.Conferences.


Writing PAM Modules, Part One
Pages: 1, 2


Function Independence

Most applications will call authentication first, then account, open the session, potentially change the authentication token with password, then close the session. This is not guaranteed, however. Modules must be able to be called independently, in any sequence.

The module must ensure that it behaves appropriately regardless of whether or not other sections have been run -- such as if password is called without authentication, or a session is opened without account management.

Module Completeness

It is perfectly acceptable to write a module which is only supposed to be called as one module type. However, for user friendliness, it can be a good idea to write functions that respond to requests for the other module types. These spurious functions should return either PAM_SERVICE_ERR or PAM_IGNORE.

Required Flags

The PAM_SILENT flag must be accepted by any module. It is passed in the flags parameter of all the functions. If the PAM_SILENT flag (which is logically ORed with any other flags) is on, the module must not pass any text errors or warnings to the application.

Argument Passing

PAM reads the configuration file for the application, parses the stack for the module type, parses the line for the specific module, and passes the appropriate arguments to the module. Each function has the parameters argc and argv, which are the count of the number of arguments and an array of pointers to the arguments, respectively.

These are similar to the parameters of the function main() in C, however, argv[0] is an argument and not the name of the module.

Generic Arguments

There are a number of arguments that all modules can expect they might be passed. A module should implement these modules (with one possible exception), but should not react to their absence.

Send debug data to the system logs using syslog().

If your module supports it, display appropriate information about user accounts, such as displaying the user's real name rather than the username in messages.

Don't send warnings to the application.

Retrieve a token from PAM_AUTHTOK and try it for this module. If it fails, ask the user for an authentication token.

Retrieve a token from PAM_AUTHTOK and use it for this module. If it fails, the module fails.

Applying this argument may cause you to break local laws regarding encryption. If so, Do not do it. No one wants anyone to get into legal trouble for writing code. If you can legally do so, the module should use the existing authentication token from the PAM_AUTHTOK item, and use it as a key to retrieve the authentication token for this module.

Final Words

This is part one of a three-part series on writing PAM modules. Part two discusses managing a Linux-PAM environment, interacting with the user, and getting and setting module data. Part three discusses the functions a module is required to provide, security issues, and response codes.

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 Kernel Archives
  • Kernel Traffic

  • Sponsored by: