Debian Codegraph @

upstream/debian-unstable/man3/pam_sm_chauthtok.3

raw
1 '\" t
2 .\" Title: pam_sm_chauthtok
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 06/29/2025
6 .\" Manual: Linux-PAM Manual
7 .\" Source: Linux-PAM
8 .\" Language: English
9 .\"
10 .TH "PAM_SM_CHAUTHTOK" "3" "06/29/2025" "Linux\-PAM" "Linux\-PAM Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 pam_sm_chauthtok \- PAM service function for authentication token management
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <security/pam_modules\&.h>
37 .fi
38 .ft
39 .HP \w'int\ pam_sm_chauthtok('u
40 .BI "int pam_sm_chauthtok(pam_handle_t\ *" "pamh" ", int\ " "flags" ", int\ " "argc" ", const\ char\ **" "argv" ");"
41 .SH "DESCRIPTION"
42 .PP
43 The
44 \fBpam_sm_chauthtok\fR
45 function is the service module\*(Aqs implementation of the
46 \fBpam_chauthtok\fR(3)
47 interface\&.
48 .PP
49 This function is used to (re\-)set the authentication token of the user\&.
50 .PP
51 Valid flags, which may be logically OR\*(Aqd with
52 \fIPAM_SILENT\fR, are:
53 .PP
54 PAM_SILENT
55 .RS 4
56 Do not emit any messages\&.
57 .RE
58 .PP
59 PAM_CHANGE_EXPIRED_AUTHTOK
60 .RS 4
61 This argument indicates to the module that the user\*(Aqs authentication token (password) should only be changed if it has expired\&. This flag is optional and
62 \fImust\fR
63 be combined with one of the following two flags\&. Note, however, the following two options are
64 \fImutually exclusive\fR\&.
65 .RE
66 .PP
67 PAM_PRELIM_CHECK
68 .RS 4
69 This indicates that the modules are being probed as to their ready status for altering the user\*(Aqs authentication token\&. If the module requires access to another system over some network it should attempt to verify it can connect to this system on receiving this flag\&. If a module cannot establish it is ready to update the user\*(Aqs authentication token it should return
70 \fBPAM_TRY_AGAIN\fR, this information will be passed back to the application\&.
71 .sp
72 If the control value
73 \fIsufficient\fR
74 is used in the password stack, the
75 \fIPAM_PRELIM_CHECK\fR
76 section of the modules following that control value is not always executed\&.
77 .RE
78 .PP
79 PAM_UPDATE_AUTHTOK
80 .RS 4
81 This informs the module that this is the call it should change the authorization tokens\&. If the flag is logically OR\*(Aqd with
82 \fBPAM_CHANGE_EXPIRED_AUTHTOK\fR, the token is only changed if it has actually expired\&.
83 .RE
84 .PP
85 The PAM library calls this function twice in succession\&. The first time with
86 \fBPAM_PRELIM_CHECK\fR
87 and then, if the module does not return
88 \fBPAM_TRY_AGAIN\fR, subsequently with
89 \fBPAM_UPDATE_AUTHTOK\fR\&. It is only on the second call that the authorization token is (possibly) changed\&.
90 .SH "RETURN VALUES"
91 .PP
92 PAM_AUTHTOK_ERR
93 .RS 4
94 The module was unable to obtain the new authentication token\&.
95 .RE
96 .PP
97 PAM_AUTHTOK_RECOVERY_ERR
98 .RS 4
99 The module was unable to obtain the old authentication token\&.
100 .RE
101 .PP
102 PAM_AUTHTOK_LOCK_BUSY
103 .RS 4
104 Cannot change the authentication token since it is currently locked\&.
105 .RE
106 .PP
107 PAM_AUTHTOK_DISABLE_AGING
108 .RS 4
109 Authentication token aging has been disabled\&.
110 .RE
111 .PP
112 PAM_PERM_DENIED
113 .RS 4
114 Permission denied\&.
115 .RE
116 .PP
117 PAM_TRY_AGAIN
118 .RS 4
119 Preliminary check was unsuccessful\&. Signals an immediate return to the application is desired\&.
120 .RE
121 .PP
122 PAM_SUCCESS
123 .RS 4
124 The authentication token was successfully updated\&.
125 .RE
126 .PP
127 PAM_USER_UNKNOWN
128 .RS 4
129 User unknown to password service\&.
130 .RE
131 .SH "SEE ALSO"
132 .PP
133 \fBpam\fR(3),
134 \fBpam_chauthtok\fR(3),
135 \fBpam_sm_chauthtok\fR(3),
136 \fBpam_strerror\fR(3),
137 \fBPAM\fR(8)