Handling the environment
Linux-PAM comes with a separate environment associated with the current PAM handle. The environment starts out empty.
extern int pam_putenv(pam_handle_t *pamh, const char *name_value);
- Attempts to set, reset, or delete the named environment variable. The
name_valueargument 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
The remaining three functions are found in
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
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
- 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
Set these with
pam_set_item() and retrieve them with
pam_get_item(). Use the PAM handle you received from
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 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
Fail delay is not guaranteed to be available, and a call to it should be bracketed with #ifdefs.
#ifdef PAM_FAIL_DELAY extern int pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec); #endif
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.
The next part of this article will describe the PAM functions that perform the actual authentication, account management, session management, and password changing.
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.