9d685beabc1010173421dd1569f15e2e743a6bab
[dragonfly.git] / contrib / libpam / doc / man / pam_chauthtok.3
1 .\" Hey Emacs! This file is -*- nroff -*- source.
2 .\" $Id: pam_chauthtok.3,v 1.2 1997/02/15 18:42:23 morgan Exp $
3 .\" $FreeBSD: src/contrib/libpam/doc/man/pam_chauthtok.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
4 .\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_chauthtok.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
5 .\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
6 .TH PAM_CHAUTHTOK 3 "1997 Jan 4" "PAM 0.55" "App. Programmers' Manual"
7 .SH NAME
8
9 pam_chauthtok \- updating authentication tokens
10
11 .SH SYNOPSIS
12 .B #include <security/pam_appl.h>
13 .sp
14 .BI "int pam_chauthtok(pam_handle_t " *pamh ", int  " flags ");"
15 .sp 2
16 .SH DESCRIPTION
17 .B pam_chauthtok
18
19 .br
20 Use this function to rejuvenate the authentication tokens (passwords
21 etc.) of an applicant user.
22
23 .br
24 Note, the application should not pre-authenticate the user, as this is
25 performed (if required) by the
26 .BR PAM
27 framework.
28
29 .br
30 The
31 .I flags
32 argument can
33 .I optionally
34 take the value,
35 .BR PAM_CHANGE_EXPIRED_AUTHTOK "."
36 In such cases the framework is only required to update those
37 authentication tokens that have expired. Without this argument, the
38 framework will attempt to obtain new tokens for all configured
39 authentication mechanisms. The details of the types and number of such
40 schemes should not concern the calling application.
41
42 .SH RETURN VALUE
43 A successful return from this function will be indicated with
44 .BR PAM_SUCCESS "."
45
46 .br
47 Specific errors of special interest when calling this function are
48
49 .br
50 .BR PAM_AUTHTOK_ERROR
51 - a valid new token was not obtained
52
53 .br
54 .BR PAM_AUTHTOK_RECOVERY_ERR
55 - old authentication token was not available
56
57 .br
58 .BR PAM_AUTHTOK_LOCK_BUSY
59 - a resource needed to update the token was locked (try again later)
60
61 .br
62 .BR PAM_AUTHTOK_DISABLE_AGING
63 - one or more of the authentication modules does not honor
64 authentication token aging
65
66 .br
67 .BR PAM_TRY_AGAIN
68 - one or more authentication mechanism is not prepared to update a
69 token at this time
70
71 .br
72 In general other return values may be returned. They should be treated
73 as indicating failure.
74
75 .SH ERRORS
76 May be translated to text with
77 .BR pam_strerror "(3). "
78
79 .SH "CONFORMING TO"
80 DCE-RFC 86.0, October 1995.
81
82 .SH BUGS
83 .sp 2
84 none known.
85
86 .SH "SEE ALSO"
87
88 .BR pam_start "(3), "
89 .BR pam_authenticate "(3), "
90 .BR pam_setcred "(3), "
91 .BR pam_get_item "(3), "
92 .BR pam_strerror "(3) "
93 and
94 .BR pam "(8)."
95
96 .br
97 Also, see the three
98 .BR PAM
99 Guides, for
100 .BR "System administrators" ", "
101 .BR "module developers" ", "
102 and
103 .BR "application developers" ". "