pam_appl-6.html
Next
pam_appl-4.html
Previous
pam_appl.html#toc5
Contents
5. 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.
5.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
pam_appl-10.html#bibliography
the bibliography
) below.
5.2 Macros supplied
Safe duplication of strings
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.
5.3 Functions supplied
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.
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.
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
.
Liberating a locally saved environment
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.
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.
pam_appl-6.html
Next
pam_appl-4.html
Previous
pam_appl.html#toc5
Contents
