HP-UX Reference (11i v3 07/02) - 3 Library Functions N-Z (vol 7)

p
pam_sm(3) pam_sm(3)
Interaction With the User
The PAM service modules do not communicate directly with the user; instead they rely on the application
to perform all such interactions. The application passes a pointer to the function,
conv( ), along with any
associated application data pointers, through the
pam_conv structure when it initiates an authentication
transaction (via a call to
pam_start() ). The service module will then use the function,
conv(),to
prompt the user for data, output error messages, and display text information. Refer to pam_start(3) for
more information. The modules are responsible for the localization of all messages to the user.
Conventions
By convention, applications that need to prompt for a user name should call
pam_set_item()
and set
the value of
PAM_USER_PROMPT
before calling pam_authenticate()
. The service module’s
pam_sm_authenticate()
function will then call
pam_get_user() to prompt for the user name.
Note that certain PAM service modules (such as a smart card module) may override the value of
PAM_USER_PROMPT
and pass in their own prompt.
Though the PAM framework enforces no rules about the module’s names, location, options and such, there
are certain conventions that all module providers are expected to follow.
By convention, the modules should be located in the
/usr/lib/security
directory.
The modules are named
libpam_service_name.1 (for example, libpam_unix.1
module).
For every such module, there should be a corresponding manual page in section 5 which should describe the
service_name it supports, the functionality of the module, along with the options it supports. The depen-
dencies should be clearly identified to the system administrator. For example, it should be made clear
whether this module is a stand-alone module or depends upon the presence of some other module. One
should also specify whether this module should come before or after some other module in the stack.
By convention, the modules should support the following options:
debug Syslog debugging information at LOG_DEBUG level. Be careful as to not log any sensitive
information such as passwords.
nowarn Turn off warning messages such as "password is about to expire"
In addition, it is recommended that the auth and the password module support the following options:
use_first_pass
Instead of prompting the user for the password, use the user’s initial password (entered
when the user was authenticated to the first authentication module in the stack) for
authentication. If the passwords do not match, or if no password has been entered, return
failure and do not prompt the user for a password. Support for this scheme allows the user
to type only one password for multiple schemes.
try_first_pass
Instead of prompting the user for the password, use the user’s initial password (entered
when the user was authenticated to the first authentication module in the stack) for
authentication. If the passwords do not match, or if no password has been entered, prompt
the user for a password after identifying which type of password (ie. UNIX, etc.) is being
requested. Support for this scheme allows the user to try to use only one password for mul-
tiple schemes, and type multiple passwords only if necessary.
use_psd Instead of prompting the user for the password, prompt for the user’s PIN (Personal
Identification Number) associated with their smart card. This allows the smart card to be
accessed, from which the password can be retrieved. With this option the user must plug
their smart card in the smart card reader connected to their system.
If an unsupported option is passed to the modules, it should syslog the error at LOG_ERR level.
The permission bits on the service module should be set such that it is not writable by either "group" or
"other". The PAM framework will not load the module if the above permission rules are not followed.
APPLICATION USAGE
Refer to pam(3) for information on thread-safety of PAM interfaces.
ERRORS
If there are any errors, the modules should log them using syslog(3C) at the LOG_ERR level.
HP-UX 11i Version 3: February 2007 − 2 − Hewlett-Packard Company 101