Here we list the interface that the conventions that all Linux-PAM modules must adhere to.
First, we cover what the module should expect from the Linux-PAM library and a PAM-aware application.
extern int pam_set_data(pam_handle_t *pamh, const char
*module_data_name, const void *data, int (*cleanup)(pam_handle_t
*pamh, const void *data, int error_status));
The modules are dynamically loadable modules. In general such files
should not contain static variables. This and the subsequent
function provide a mechanism for a module to associate some data with
the handle pamh
. Typically a module will call the
pam_set_data
function to register some data under a (hopefully)
unique module_data_name
. The data is availible for use by other
modules too but not by an application.
The function cleanup
is associated with the data
and, if
non-NULL
, it is called when this data is over-written or
following a call to pam_end
(see pam_appl.html).
extern int pam_get_data(const pam_handle_t *pamh, const char
*module_data_name, const void **data);
This function together with the previous one provides a method of
associating module-specific data with the handle pamh
. A
successful call to pam_get_data
will result in *data
pointing to the data associated with the module_data_name
. Note,
this data is not
a copy and should be treated as constant
by the module.
extern int pam_set_item(pam_handle_t *pamh, int item_type, const void
*item);
This function is used to (re)set the value of one of the
item_type
s. The reader is urged to read the entry for this
function in the Linux-PAM application developers' manual,
pam_appl.html.
In addition to the item
s listed there, the module can set the
following two item_tpye
s:
PAM_AUTHTOK
The authentication token (password)
PAM_OLDAUTHTOK
The old authentication token
extern int pam_get_item(const pam_handle_t *pamh, int item_type,
void **item);
This function is used to obtain the value of the specified
item_type
. It is better documented in the Linux-PAM
application developers' manual, pam_appl.html. However, the module
is additionally privileged to read the above authentication tokens
(PAM_AUTHTOK
and PAM_OLDAUTHTOK
). Note it is required that
these tokens are made NULL
before process control passes back to
the application.
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 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/presented to the user.
The reader might care to read the description of the pam_conv
structure, written from the perspective of the application developer
in pam_appl.html.
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 is 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.
extern int pam_get_user(pam_handle_t *pamh, );
extern const char *pam_strerror(int errnum);
This function returns some text describing the Linux-PAM error
associated with the argument errnum
.