PAM Library Functions pamsmchauthtok(3PAM)
NAME
pamsmchauthtok - service provider implementation for
pamchauthtok
SYNOPSIS
cc [ flag ...] file ... -lpam [ library ... ]
#include
#include
int pamsmchauthtok(pamhandlet *pamh, int flags, int argc,
const char **argv);
DESCRIPTION
In response to a call to pamchauthtok() the PAM framework
calls pamsmchauthtok(3PAM) from the modules listed in the
pam.conf(4) file. The password management provider supplies
the back-end functionality for this interface function.
The pamsmchauthtok() function changes the authentication
token associated with a particular user referenced by the
authentication handle pamh.
The following flag may be passed to pamchauthtok():
PAMSILENT The password service should
not generate any messages.
PAMCHANGEXPIREDAUTHTOK The password service should
only update those passwords
that have aged. If this flag
is not passed, the password
service should update all
passwords.
PAMPRELIMCHECK The password service should
only perform preliminary
checks. No passwords should be
updated.
PAMNOAUTHTOKCHECK The password service should
not perform conformance checks
on the structure of the pass-
word. Conformance checks do
not apply to verification that
the same password was entered
during both passes.
SunOS 5.11 Last change: 1 Mar 2005 1
PAM Library Functions pamsmchauthtok(3PAM)
PAMUPDATEAUTHTOK The password service should
update passwords.
Note that PAMPRELIMCHECK and PAMUPDATEAUTHTOK cannot be
set at the same time.
Upon successful completion of the call, the authentication
token of the user will be ready for change or will be
changed, depending upon the flag, in accordance with the
authentication scheme configured within the system.
The argc argument represents the number of module options
passed in from the configuration file pam.conf(4). The argv
argument specifies the module options, which are interpreted
and processed by the password management service. Please
refer to the specific module man pages for the various
available options.
It is the responsibility of pamsmchauthtok() to determine
if the new password meets certain strength requirements.
pamsmchauthtok() may continue to re-prompt the user (for a
limited number of times) for a new password until the pass-
word entered meets the strength requirements.
Before returning, pamsmchauthtok() should call
pamgetitem() and retrieve both PAMAUTHTOK and
PAMOLDAUTHTOK. If both are NUL, pamsmchauthtok() should
set them to the new and old passwords as entered by the
user.
RETURN VALUES
Upon successful completion, PAMSUCES must be returned.
The following values may also be returned:
PAMPERMDENIED No permission.
PAMAUTHTOKER Authentication token manipula-
tion error.
PAMAUTHTOKRECOVERYER Old authentication token cannot
be recovered.
SunOS 5.11 Last change: 1 Mar 2005 2
PAM Library Functions pamsmchauthtok(3PAM)
PAMAUTHTOKLOCKBUSY Authentication token lock busy.
PAMAUTHTOKDISABLEAGING Authentication token aging dis-
abled.
PAMUSERUNKNOWN User unknown to password ser-
vice.
PAMTRYAGAIN Preliminary check by password
service failed.
ATRIBUTES
See attributes(5) for description of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Stable
MT-Level MT-Safe with exceptions
SEE ALSO
ping(1M), pam(3PAM), pamchauthtok(3PAM),
pamgetdata(3PAM), pamgetitem(3PAM), pamsetdata(3PAM),
libpam(3LIB), pam.conf(4), attributes(5)
NOTES
The PAM framework invokes the password services twice. The
first time the modules are invoked with the flag,
PAMPRELIMCHECK. During this stage, the password modules
should only perform preliminary checks. For example, they
may ping remote name services to see if they are ready for
updates. If a password module detects a transient error such
as a remote name service temporarily down, it should return
PAMTRYAGAIN to the PAM framework, which will immediately
return the error back to the application. If all password
modules pass the preliminary check, the PAM framework
invokes the password services again with the flag,
PAMUPDATEAUTHTOK. During this stage, each password module
should proceed to update the appropriate password. Any error
will again be reported back to application.
SunOS 5.11 Last change: 1 Mar 2005 3
PAM Library Functions pamsmchauthtok(3PAM)
If a service module receives the flag
PAMCHANGEXPIREDAUTHTOK, it should check whether the
password has aged or expired. If the password has aged or
expired, then the service module should proceed to update
the password. If the status indicates that the password has
not yet aged or expired, then the password module should
return PAMIGNORE.
If a user's password has aged or expired, a PAM account
module could save this information as state in the authenti-
cation handle, pamh, using pamsetdata(). The related pass-
word management module could retrieve this information using
pamgetdata() to determine whether or not it should prompt
the user to update the password for this particular module.
The interfaces in libpam are MT-Safe only if each thread
within the multithreaded application uses its own PAM han-
dle.
If the PAMREPOSITORY itemtype is set and a service module
does not recognize the type, the service module does not
process any information, and returns PAMIGNORE. If the
PAMREPOSITORY itemtype is not set, a service module per-
forms its default action.
SunOS 5.11 Last change: 1 Mar 2005 4
|
