Initial import of the CDE 2.1.30 sources from the Open Group.

cde/lib/pam/man/man3/pam_chauthtok.3

@@ -0,0 +1,100 @@
+.\" $XConsortium: pam_chauthtok.3 /main/5 1996/10/29 15:18:27 drk $
+.\" Sccs id goes here
+'\"macro stdmacro
+.\" Copyright (c) 1995, Sun Microsystems, Inc. 
+.\" All Rights Reserved
+.nr X
+.TH pam_chauthtok 3 "9 Jan 1996"
+.SH NAME
+pam_chauthtok
+\- perform passord related functions within the PAM framework
+.SH SYNOPSIS
+.LP
+.B cc
+.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
+.B \-lpam
+.RI "[ " "library" " \|.\|.\|. ]"
+.LP
+.nf
+.ft 3
+#include <security/pam_appl.h>
+.ft
+.fi
+.LP
+.BI "int pam_chauthtok(pam_handle_t " "*pamh" ,
+.BI "const int" " flags");
+.SH DESCRIPTION
+.IX "pam_chauthtok" "" "\fLpam_chauthtok\fP \(em request changing authentication token or get/set authentication attributes"
+.B pam_chauthtok(\|)
+is called to change the authentication token
+associated with a particular user
+referenced by the authentication handle,
+.IR pamh.
+.LP
+The following flag may be passed in to
+.BR pam_chauthtok(\|) :
+.RS
+.IP PAM_SILENT 30
+The password service should not generate any messages
+.IP PAM_CHANGE_EXPIRED_AUTHTOK 30
+The password service should only update those passwords that have aged.
+If this flag is not passed,
+all password services should update their passwords.
+.RE
+.LP
+Upon successful completion of the call, the authentication
+token of the user will be changed in accordance with the 
+password service configured in the system through
+.BR pam.conf (4).
+.SH NOTES
+The flag
+.SM PAM_CHANGE_EXPIRED_AUTHTOK
+is typically used by a
+.B login
+application which has determined that the user's password has aged or expired.
+Before allowing the user to login, the
+.B login
+application may invoke
+.B pam_chauthtok(\|)
+with this flag to allow the user to update the password.
+Typically applications such as
+.BR passwd (1)
+should not use this flag.
+.PP
+.B pam_chauthtok(\|)
+performs a preliminary check before attempting to update
+passwords. This check is performed for each
+password module in the stack as listed in 
+.BR pam.conf (4).
+The check may include pinging remote name services to determine
+if they are available. If
+.B pam_chauthtok(\|)
+returns
+PAM_TRY_AGAIN,
+then the check has failed, and passwords are not updated.
+.SH "RETURN VALUES"
+.PP
+Upon successful completion, PAM_SUCCESS is returned.
+In addition to the error return values described in
+.BR pam (3),
+the following values may be returned:
+.RS
+.IP PAM_PERM_DENIED 34
+No permission
+.IP PAM_AUTHTOK_ERR 34
+Authentication token manipulation error
+.IP PAM_AUTHTOK_RECOVERY_ERR 34
+Authentication information cannot be recovered
+.IP PAM_AUTHTOK_LOCK_BUSY 34
+Authentication token lock busy
+.IP PAM_AUTHTOK_DISABLE_AGING 34
+Authentication token aging disabled
+.IP PAM_USER_UNKNOWN 34
+User unknown to password service
+.IP PAM_TRY_AGAIN 34
+Preliminary check by password service failed
+.RE
+.SH "SEE ALSO"
+.BR pam (3),
+.BR pam_start (3),
+.BR pam_authenticate (3)