1pam_sm_chauthtok(3PAM) PAM Library Functions pam_sm_chauthtok(3PAM)
2
6 pam_sm_chauthtok - service provider implementation for pam_chauthtok
7
9 cc [ flag ...] file ... -lpam [ library ... ]
10 #include <security/pam_appl.h>
11 #include <security/pam_modules.h>
12 int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int argc,
14 const char **argv);
15
18 In response to a call to pam_chauthtok() the PAM framework calls
19 pam_sm_chauthtok(3PAM) from the modules listed in the pam.conf(4) file.
20 The password management provider supplies the back-end functionality
21 for this interface function.
22 The pam_sm_chauthtok() function changes the authentication token asso‐
25 ciated with a particular user referenced by the authentication handle
26 pamh.
27 The following flag may be passed to pam_chauthtok():
30 PAM_SILENT The password service should not generate
32 any messages.
33 PAM_CHANGE_EXPIRED_AUTHTOK The password service should only update
36 those passwords that have aged. If this
37 flag is not passed, the password service
38 should update all passwords.
39 PAM_PRELIM_CHECK The password service should only perform
42 preliminary checks. No passwords should
43 be updated.
44 PAM_NO_AUTHTOK_CHECK The password service should not perform
47 conformance checks on the structure of
48 the password. Conformance checks do not
49 apply to verification that the same pass‐
50 word was entered during both passes.
51 PAM_UPDATE_AUTHTOK The password service should update pass‐
54 words.
55 Note that PAM_PRELIM_CHECK and PAM_UPDATE_AUTHTOK cannot be set at the
59 same time.
60 Upon successful completion of the call, the authentication token of the
63 user will be ready for change or will be changed, depending upon the
64 flag, in accordance with the authentication scheme configured within
65 the system.
66 The argc argument represents the number of module options passed in
69 from the configuration file pam.conf(4). The argv argument specifies
70 the module options, which are interpreted and processed by the password
71 management service. Please refer to the specific module man pages for
72 the various available options.
73 It is the responsibility of pam_sm_chauthtok() to determine if the new
76 password meets certain strength requirements. pam_sm_chauthtok() may
77 continue to re-prompt the user (for a limited number of times) for a
78 new password until the password entered meets the strength require‐
79 ments.
80 Before returning, pam_sm_chauthtok() should call pam_get_item() and
83 retrieve both PAM_AUTHTOK and PAM_OLDAUTHTOK. If both are NULL,
84 pam_sm_chauthtok() should set them to the new and old passwords as
85 entered by the user.
86
88 Upon successful completion, PAM_SUCCESS must be returned. The following
89 values may also be returned:
90 PAM_PERM_DENIED No permission.
92 PAM_AUTHTOK_ERR Authentication token manipulation error.
95 PAM_AUTHTOK_RECOVERY_ERR Old authentication token cannot be recov‐
98 ered.
99 PAM_AUTHTOK_LOCK_BUSY Authentication token lock busy.
102 PAM_AUTHTOK_DISABLE_AGING Authentication token aging disabled.
105 PAM_USER_UNKNOWN User unknown to password service.
108 PAM_TRY_AGAIN Preliminary check by password service
111 failed.
112
115 See attributes(5) for description of the following attributes:
116 ┌─────────────────────────────┬─────────────────────────────┐
121 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
122 ├─────────────────────────────┼─────────────────────────────┤
123 │Interface Stability │ Stable │
124 ├─────────────────────────────┼─────────────────────────────┤
125 │MT-Level │MT-Safe with exceptions │
126 └─────────────────────────────┴─────────────────────────────┘
127
129 ping(1M), pam(3PAM), pam_chauthtok(3PAM), pam_get_data(3PAM),
130 pam_get_item(3PAM), pam_set_data(3PAM), libpam(3LIB), pam.conf(4),
131 attributes(5)
132
134 The PAM framework invokes the password services twice. The first time
135 the modules are invoked with the flag, PAM_PRELIM_CHECK. During this
136 stage, the password modules should only perform preliminary checks. For
137 example, they may ping remote name services to see if they are ready
138 for updates. If a password module detects a transient error such as a
139 remote name service temporarily down, it should return PAM_TRY_AGAIN to
140 the PAM framework, which will immediately return the error back to the
141 application. If all password modules pass the preliminary check, the
142 PAM framework invokes the password services again with the flag,
143 PAM_UPDATE_AUTHTOK. During this stage, each password module should pro‐
144 ceed to update the appropriate password. Any error will again be
145 reported back to application.
146 If a service module receives the flag PAM_CHANGE_EXPIRED_AUTHTOK, it
149 should check whether the password has aged or expired. If the password
150 has aged or expired, then the service module should proceed to update
151 the password. If the status indicates that the password has not yet
152 aged or expired, then the password module should return PAM_IGNORE.
153 If a user's password has aged or expired, a PAM account module could
156 save this information as state in the authentication handle, pamh,
157 using pam_set_data(). The related password management module could
158 retrieve this information using pam_get_data() to determine whether or
159 not it should prompt the user to update the password for this particu‐
160 lar module.
161 The interfaces in libpam are MT-Safe only if each thread within the
164 multithreaded application uses its own PAM handle.
165 If the PAM_REPOSITORY item_type is set and a service module does not
168 recognize the type, the service module does not process any informa‐
169 tion, and returns PAM_IGNORE. If the PAM_REPOSITORY item_type is not
170 set, a service module performs its default action.
171SunOS 5.11 1 Mar 2005 pam_sm_chauthtok(3PAM)