Previous Next Table of Contents

4. A library of miscellaneous helper functions

To aid the work of the application developer a library of miscellaneous functions is provided. It is called libpam_misc, and contains functions for allocating memory (securely), a text based conversation function, and routines for enhancing the standard PAM-environment variable support.

4.1 Requirements

The functions, structures and macros made available by this library can be defined by including <security/pam_misc.h>. It should be noted that this library is specific to Linux-PAM and is not referred to in the defining DCE-RFC (see the bibliography) below.

4.2 Functions supplied

Safe string duplication

extern char *xstrdup(const char *s)
Return a duplicate copy of the NUL terminated string, s. NULL is returned if there is insufficient memory available for the duplicate or if s=NULL.

A text based conversation function

extern int misc_conv(int num_msg, const struct pam_message **msgm,
                     struct pam_response **response, void *appdata_ptr);

This is a function that will prompt the user with the appropriate comments and obtain the appropriate inputs as directed by authentication modules.

Transcribing an environment to that of Linux-PAM

extern int pam_misc_paste_env(pam_handle_t *pamh,
                              const char * const * user_env);

This function takes the supplied list of environment pointers and uploads its contents to the Linux-PAM environment. Success is indicated by PAM_SUCCESS.

Saving the Linux-PAM environment for later use

extern char **pam_misc_copy_env(pam_handle_t *pamh);

This function returns a pointer to a list of environment variables that are a direct copy of the Linux-PAM environment. The memory associated with these variables are the responsibility of the application and should be liberated with a call to pam_misc_drop_env().

Liberating a locally saved environment

extern char **pam_misc_drop_env(char **env);

This function is defined to complement the pam_misc_copy_env() function. It liberates the memory associated with env, overwriting with 0 all memory before free()ing it.

BSD like Linux-PAM environment variable setting

extern int pam_misc_setenv(pam_handle_t *pamh, const char *name,
                           const char *value, int readonly);

This function performs a task equivalent to pam_putenv(), its syntax is, however, more like the BSD style function; setenv(). The name and value are concatenated with an ``='' to form a name_value and passed to pam_putenv(). If, however, the Linux-PAM variable is already set, the replacement will only be applied if the last argument, readonly, is zero.


Previous Next Table of Contents