usr/src/man/man3pam/pam_sm_chauthtok.3pam

   1 '\" te
   2 .\"  Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PAM_SM_CHAUTHTOK 3PAM "Mar 1, 2005"
   7 .SH NAME
   8 pam_sm_chauthtok \- service provider implementation for pam_chauthtok
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ...] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
  13 #include <security/pam_appl.h>
  14 #include <security/pam_modules.h>
  15
  16 \fBint\fR \fBpam_sm_chauthtok\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIflags\fR, \fBint\fR \fIargc\fR,
  17      \fBconst char **\fR\fIargv\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 In response to a call to \fBpam_chauthtok()\fR the \fBPAM\fR framework calls
  24 pam_sm_chauthtok(3PAM) from the modules listed in the \fBpam.conf\fR(4) file.
  25 The password management provider supplies the back-end functionality for this
  26 interface function.
  27 .sp
  28 .LP
  29 The \fBpam_sm_chauthtok()\fR function changes the authentication token
  30 associated with a particular user referenced by the authentication handle
  31 \fIpamh\fR.
  32 .sp
  33 .LP
  34 The following flag may be passed to \fBpam_chauthtok()\fR:
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fBPAM_SILENT\fR\fR
  39 .ad
  40 .RS 30n
  41 The password service should not generate any messages.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBPAM_CHANGE_EXPIRED_AUTHTOK\fR\fR
  48 .ad
  49 .RS 30n
  50 The password service should only update those passwords that have aged. If this
  51 flag is not passed, the password service should update all passwords.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBPAM_PRELIM_CHECK\fR\fR
  58 .ad
  59 .RS 30n
  60 The password service should only perform preliminary checks. No passwords
  61 should be updated.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fBPAM_NO_AUTHTOK_CHECK\fR\fR
  68 .ad
  69 .RS 30n
  70 The password service should not perform conformance checks on the structure of
  71 the password. Conformance checks do not apply to verification that the same
  72 password was entered during both passes.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBPAM_UPDATE_AUTHTOK\fR\fR
  79 .ad
  80 .RS 30n
  81 The password service should update passwords.
  82 .RE
  83
  84 .sp
  85 .LP
  86 Note that \fBPAM_PRELIM_CHECK\fR and \fBPAM_UPDATE_AUTHTOK\fR cannot be set at
  87 the same time.
  88 .sp
  89 .LP
  90 Upon successful completion of the call, the authentication token of the user
  91 will be ready for change or will be changed, depending upon the flag, in
  92 accordance with the authentication scheme configured within the system.
  93 .sp
  94 .LP
  95 The \fIargc\fR argument represents the number of module options passed in from
  96 the configuration file \fBpam.conf\fR(4). The \fIargv\fR argument specifies the
  97 module options, which are interpreted and processed by the password management
  98 service. Please refer to the specific module man pages for the various
  99 available \fIoptions\fR.
 100 .sp
 101 .LP
 102 It is the responsibility of \fBpam_sm_chauthtok()\fR to determine if the new
 103 password meets certain strength requirements. \fBpam_sm_chauthtok()\fR may
 104 continue to re-prompt the user (for a limited number of times) for a new
 105 password until the password entered meets the strength requirements.
 106 .sp
 107 .LP
 108 Before returning, \fBpam_sm_chauthtok()\fR should call  \fBpam_get_item()\fR
 109 and retrieve both \fBPAM_AUTHTOK\fR and \fBPAM_OLDAUTHTOK\fR. If both are
 110 \fINULL\fR, \fBpam_sm_chauthtok()\fR should set them to the new and old
 111 passwords as entered by the user.
 112 .SH RETURN VALUES
 113 .sp
 114 .LP
 115 Upon successful completion, \fBPAM_SUCCESS\fR must be returned. The following
 116 values may also be returned:
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBPAM_PERM_DENIED\fR\fR
 121 .ad
 122 .RS 29n
 123 No permission.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBPAM_AUTHTOK_ERR\fR\fR
 130 .ad
 131 .RS 29n
 132 Authentication token manipulation error.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBPAM_AUTHTOK_RECOVERY_ERR\fR\fR
 139 .ad
 140 .RS 29n
 141 Old authentication token cannot be recovered.
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBPAM_AUTHTOK_LOCK_BUSY\fR\fR
 148 .ad
 149 .RS 29n
 150 Authentication token lock busy.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBPAM_AUTHTOK_DISABLE_AGING\fR\fR
 157 .ad
 158 .RS 29n
 159 Authentication token aging disabled.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBPAM_USER_UNKNOWN\fR\fR
 166 .ad
 167 .RS 29n
 168 User unknown to password service.
 169 .RE
 170
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBPAM_TRY_AGAIN\fR\fR
 175 .ad
 176 .RS 29n
 177 Preliminary check by password service failed.
 178 .RE
 179
 180 .SH ATTRIBUTES
 181 .sp
 182 .LP
 183 See \fBattributes\fR(5) for description of the following attributes:
 184 .sp
 185
 186 .sp
 187 .TS
 188 box;
 189 c | c
 190 l | l .
 191 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 192 _
 193 Interface Stability      Stable
 194 _
 195 MT-Level        MT-Safe with exceptions
 196 .TE
 197
 198 .SH SEE ALSO
 199 .sp
 200 .LP
 201 \fBping\fR(1M), \fBpam\fR(3PAM), \fBpam_chauthtok\fR(3PAM),
 202 \fBpam_get_data\fR(3PAM), \fBpam_get_item\fR(3PAM), \fBpam_set_data\fR(3PAM),
 203 \fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5)
 204 .SH NOTES
 205 .sp
 206 .LP
 207 The \fBPAM\fR framework invokes the password services twice. The first time the
 208 modules are invoked with the flag, \fBPAM_PRELIM_CHECK\fR. During this stage,
 209 the password modules should only perform preliminary checks. For example, they
 210 may \fBping\fR remote name services to see if they are ready for updates. If a
 211 password module detects a transient error such as a remote name service
 212 temporarily down, it should return \fBPAM_TRY_AGAIN\fR to the \fBPAM\fR
 213 framework, which will immediately return the error back to the application. If
 214 all password modules pass the preliminary check, the \fBPAM\fR framework
 215 invokes the password services again with the flag, \fBPAM_UPDATE_AUTHTOK\fR.
 216 During this stage, each password module should proceed to update the
 217 appropriate password. Any error will again be reported back to application.
 218 .sp
 219 .LP
 220 If a service module receives the flag \fBPAM_CHANGE_EXPIRED_AUTHTOK\fR, it
 221 should check whether the password has aged or expired. If the password has aged
 222 or expired, then the service module should proceed to update the password. If
 223 the status indicates that the password has not yet aged or expired, then the
 224 password module should return \fBPAM_IGNORE\fR.
 225 .sp
 226 .LP
 227 If a user's password has aged or expired, a \fBPAM\fR account module could save
 228 this information as state in the authentication handle, \fIpamh\fR, using
 229 \fBpam_set_data()\fR. The related password management module could retrieve
 230 this information using \fBpam_get_data()\fR to determine whether or not it
 231 should prompt the user to update the password for this particular module.
 232 .sp
 233 .LP
 234 The interfaces in \fBlibpam\fR are MT-Safe only if each thread within the
 235 multithreaded application uses its own \fBPAM\fR handle.
 236 .sp
 237 .LP
 238 If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is set and a service module does
 239 not recognize the type, the service module does not process any information,
 240 and returns \fBPAM_IGNORE\fR. If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is
 241 not set, a service module performs its default action.