.\" Hey Emacs! This file is -*- nroff -*- source.
.\" $Id$
.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
.TH PAM_CHAUTHTOK 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual"
.SH NAME

pam_chauthtok \- updating authentication tokens

.SH SYNOPSIS
.B #include <security/pam_appl.h>
.sp
.BI "int pam_chauthtok(pam_handle_t " *pamh ", int  " flags ");"
.sp 2
.SH DESCRIPTION
.B pam_chauthtok

.br
Use this function to rejuvenate the authentication tokens (passwords
etc.) of an applicant user.

.br
Note, the application should not pre-authenticate the user, as this is
performed (if required) by the
.BR Linux-PAM
framework.

.br
The
.I flags
argument can
.I optionally
take the value,
.BR PAM_CHANGE_EXPIRED_AUTHTOK "."
In such cases the framework is only required to update those
authentication tokens that have expired. Without this argument, the
framework will attempt to obtain new tokens for all configured
authentication mechanisms. The details of the types and number of such
schemes should not concern the calling application.

.SH RETURN VALUE
A successful return from this function will be indicated with
.BR PAM_SUCCESS "."

.br
Specific errors of special interest when calling this function are

.br
.BR PAM_AUTHTOK_ERROR
- a valid new token was not obtained

.br
.BR PAM_AUTHTOK_RECOVERY_ERR
- old authentication token was not available

.br
.BR PAM_AUTHTOK_LOCK_BUSY
- a resource needed to update the token was locked (try again later)

.br
.BR PAM_AUTHTOK_DISABLE_AGING
- one or more of the authentication modules does not honor
authentication token aging

.br
.BR PAM_TRY_AGAIN
- one or more authentication mechanism is not prepared to update a
token at this time

.br
In general other return values may be returned. They should be treated
as indicating failure.

.SH ERRORS
May be translated to text with
.BR pam_strerror "(3). "

.SH "CONFORMING TO"
DCE-RFC 86.0, October 1995.

.SH BUGS
.sp 2
none known.

.SH "SEE ALSO"

.BR pam_start "(3), "
.BR pam_authenticate "(3), "
.BR pam_setcred "(3), "
.BR pam_get_item "(3), "
.BR pam_strerror "(3) "
and
.BR pam "(8)."

.br
Also, see the three
.BR Linux-PAM
Guides, for
.BR "System administrators" ", "
.BR "module developers" ", "
and
.BR "application developers" ". "