oreilly.comSafari Books Online.Conferences.


Writing PAM-Capable Applications, Part One
Pages: 1, 2, 3

Handling the environment

Linux-PAM comes with a separate environment associated with the current PAM handle. The environment starts out empty.

Related Reading

Linux in a Nutshell
By Ellen Siever, Stephen Spainhour, Jessica P. Hekman, Stephen Figgins

extern int pam_putenv(pam_handle_t *pamh, const char *name_value);
Attempts to set, reset, or delete the named environment variable. The name_value argument is a NULL terminated (C style) string. Valid formats are:
Sets "name" to "value"

Sets "name" to the empty string

Deletes "name"

extern const char *pam_getenv(pam_handle_t *pamh, const char *name);
Returns the value of the named Linux-PAM environment variable, or NULL if there is a failure.

extern const char * const *pam_getenvlist(pam_handle_t *pamh);
Returns a pointer to a read-only list of the current Linux-PAM environment. If you want a writable copy of the list, use pam_misc_copy_env().

The remaining three functions are found in pam_misc.h:

extern int pam_misc_paste_env(pam_handle_t *pamh, const char * const * user_env);
Copies the parameter (a list of environment pointers) to the Linux-PAM environment.

extern char **pam_misc_copy_env(pam_handle_t *pamh);
Returns a pointer to a list of environment variables that are a copy of the Linux-PAM environment.

extern char **pam_misc_drop_env(char **env);
Liberates the memory used by pam_misc_copy_env().

Setting PAM items

PAM stores eight items, available to be set or retrieved by both application and module.

About the application:

The PAM name of the application, not necessarily the name the user sees. For security, hard-code this into the application or set it in a sysadmin-only configuration file. This is used in pam_start().

The conversation structure.

Used only if the default fail delay function won't work for your application. Leave it alone in most cases.

About the user:

The username to be authenticated against.

The prompt the module should use if asking for a username.

The user requesting authentication, usually the username of the user calling the application.

About the machine:

The hostname of the machine requesting authentication.

The terminal name (console-based apps) or $DISPLAY (GUI-based apps). You can retrieve the terminal name with ttyname().

Set these with pam_set_item() and retrieve them with pam_get_item(). Use the PAM handle you received from pam_start(). item_type is one of the codes in this section. item is a pointer to a string. The functions return PAM_SUCCESS if they succeed and other PAM codes if they fail.

In C++, you may need to call them with code like retval = pam_get_item(pamh, PAM_SERVICE, &static_cast<const void*> (item));.

extern int pam_set_item(pam_handle_t *pamh, int item_type,
                        const void *item);

extern int pam_get_item(const pam_handle_t *pamh, int item_type,
                        const void **item);

pam_get_item() returns a pointer to the actual data and this data should NOT be freed or overwritten. Use pam_set_item() if you want to change an item's contents.

The username

The module calls the function pam_get_user() to get the username. If you know who you want the user to authenticate as, you can set it in pam_start() or using pam_set_item(). If you don't set it, pam_get_user() will use the conversation function and the PAM_USER_PROMPT to request the username.


If you want to limit how frequently people can try to authenticate, set a delay (in microseconds) using this function. This can hinder brute force or timed attacks.

If the fail delay is set, failed authentication in pam_authenticate will cause a delay in returning control to the application. The exact display is randomly chosen, based on the longest value passed to pam_fail_delay.

Fail delay is not guaranteed to be available, and a call to it should be bracketed with #ifdefs.

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

In some circumstances, the default function is not appropriate. The information to write a fail delay function is in the PAM Application Developer's Guide.

Final words

The next part of this article will describe the PAM functions that perform the actual authentication, account management, session management, and password changing.

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: