The conversation mechanism

Following the call pam_get_item(pamh,PAM_CONV,&item), the pointer item points to a conversation-function that provides limited but direct access to the application. The purpose of this function is to allow the module to prompt the user for their password and pass other information in a manner consistent with the application. For example, an X-windows based program might pop up a dialog box to report a login failure. Just as the application should not be concerned with the method of authentication, so the module should not dictate the manner in which input (output) is obtained from (presented to) to the user.

The reader is strongly urged to read the more complete description of the pam_conv structure, written from the perspective of the application developer, in the Linux-PAM Application Developers' Guide.

The pam_response structure returned after a call to the pam_conv function must be free()'d by the module. Since the call to the conversation function originates from the module, it is clear that either this pam_response structure could be either statically or dynamically (using malloc() etc.) allocated within the application. Repeated calls to the conversation function would likely overwrite static memory, so it is required that for a successful return from the conversation function the memory for the response structure is dynamically allocated by the application with one of the malloc() family of commands and must be free()'d by the module.

If the pam_conv mechanism is used to enter authentication tokens, the module should either pass the result to the pam_set_item() library function, or copy it itself. In such a case, once the token has been stored (by one of these methods or another one), the memory returned by the application should be overwritten with 0's, and then free()'d.

The return values for this function are listed in the Linux-PAM Application Developers' Guide.

Getting the name of a user

Synopsis:

extern int pam_get_user(pam_handle_t *pamh
                        , const char **user
                        , const char *prompt
                        );

This is a Linux-PAM library function that returns the (prospective) name of the user. To determine the username it does the following things, in this order:

• checks what pam_get_item(pamh, PAM_USER, ... ); would have returned. If this is not NULL this is what it returns. Otherwise,
• obtains a username from the application via the pam_conv mechanism, it prompts the user with the first non-NULL string in the following list:
  • The prompt argument passed to the function
  • What is returned by pam_get_item(pamh,PAM_USER_PROMPT, ... );
  • The default prompt: ``Please enter username: ''

By whatever means the username is obtained, a pointer to it is returned as the contents of *user. Note, this memory should not be free()'d by the module. Instead, it will be liberated on the next call to pam_get_user(), or by pam_end() when the application ends its interaction with Linux-PAM.

Also, in addition, it should be noted that this function sets the PAM_USER item that is associated with the pam_[gs]et_item() function.

Setting a Linux-PAM environment variable

Synopsis:

extern int pam_putenv(pam_handle_t *pamh, const char *name_value);

Linux-PAM (0.54+) comes equipped with a series of functions for maintaining a set of environment variables. The environment is initialized by the call to pam_start() and is erased with a call to pam_end(). This environment is associated with the pam_handle_t pointer returned by the former call.

The default environment is all but empty. It contains a single NULL pointer, which is always required to terminate the variable-list. The pam_putenv() function can be used to add a new environment variable, replace an existing one, or delete an old one.

• Adding/replacing a variable
  To add or overwrite a Linux-PAM environment variable the value of the argument name_value, should be of the following form:

  name_value="VARIABLE=VALUE OF VARIABLE"
  

  Here, VARIABLE is the environment variable's name and what follows the `=' is its (new) value. (Note, that "VARIABLE=" is a valid value for name_value, indicating that the variable is set to "".)
• Deleting a variable
  To delete a Linux-PAM environment variable the value of the argument name_value, should be of the following form:

  name_value="VARIABLE"
  

  Here, VARIABLE is the environment variable's name and the absence of an `=' indicates that the variable should be removed.

In all cases PAM_SUCCESS indicates success.

Getting a Linux-PAM environment variable

Synopsis:

extern const char *pam_getenv(pam_handle_t *pamh, const char *name);

This function can be used to return the value of the given variable. If the returned value is NULL, the variable is not known.

Listing the Linux-PAM environment

Synopsis:

extern char * const *pam_getenvlist(pam_handle_t *pamh);

This function returns a pointer to the entire Linux-PAM environment array. At first sight the type of the returned data may appear a little confusing. It is basically a read-only array of character pointers, that lists the NULL terminated list of environment variables set so far.

Although, this is not a concern for the module programmer, we mention here that an application should be careful to copy this entire array before executing pam_end() otherwise all the variable information will be lost. (There are functions in libpam_misc for this purpose: pam_misc_copy_env() and pam_misc_drop_env().)

2.2 Other functions provided by libpam

Understanding errors

• ex