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.
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.
x_strdup(const char *s)
This macro is a replacement for the xstrdup() function that was
present in earlier versions of the library and which clashed horribly
with a number of applications. It returns a duplicate copy of the
NUL terminated string, s. NULL is returned if there is
insufficient memory available for the duplicate or if s is
NULL to begin with.
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.
In addition to simply slotting into the appropriate struct
pam_conv, this function provides some time-out facilities. The
function exports five variables that can be used by an application
programmer to limit the amount of time this conversation function will
spend waiting for the user to type something.
The five variables are as follows:
extern time_t pam_misc_conv_warn_time;This variable contains the time (as returned by time()) that
the user should be first warned that the clock is ticking. By default
it has the value 0, which indicates that no such warning will be
given. The application may set its value to sometime in the future,
but this should be done prior to passing control to the Linux-PAM
library.
extern const char *pam_misc_conv_warn_line;Used in conjuction with pam_misc_conv_warn_time, this variable is
a pointer to the string that will be displayed when it becomes time to
warn the user that the timeout is approaching. Its default value is
``..\a.Time is running out...\n'', but this can be changed
by the application prior to passing control to Linux-PAM.
extern time_t pam_misc_conv_die_time;This variable contains the time (as returned by time()) that
the conversation will time out. By default it has the value 0,
which indicates that the conversation function will not timeout. The
application may set its value to sometime in the future, this should
be done prior to passing control to the Linux-PAM library.
extern const char *pam_misc_conv_die_line;Used in conjuction with pam_misc_conv_die_time, this variable is
a pointer to the string that will be displayed when the conversation
times out. Its default value is ``..\a.Sorry, your time is
up!\n'', but this can be changed by the application prior to
passing control to Linux-PAM.
extern int pam_misc_conv_died;Following a return from the Linux-PAM libraray, the value of this
variable indicates whether the conversation has timed out. A value of
1 indicates the time-out occurred.
The following two function pointers are available for supporting binary
prompts in the conversation function. They are optimized for the
current incarnation of the libpamc library and are subject to
change.
extern int (*pam_binary_handler_fn)(void *appdata, pamc_bp_t
*prompt_p);This function pointer is initialized to NULL but can be filled
with a function that provides machine-machine (hidden) message
exchange. It is intended for use with hidden authentication protocols
such as RSA or Diffie-Hellman key exchanges. (This is still under
development.)
extern int (*pam_binary_handler_free)(void *appdata,
pamc_bp_t *delete_me);This function pointer is initialized to PAM_BP_RENEW(delete_me, 0,
0), but can be redefined as desired by the application.
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.
extern char **pam_misc_drop_env(char **env);
This function is defined to complement the pam_getenvlist()
function. It liberates the memory associated with env,
overwriting with 0 all memory before free()ing it.
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.