.\"$Id: pw_auth.3,v 1.10 2005/04/02 16:10:24 kloczek Exp $ .\" Copyright 1992 - 1993, Julianne Frances Haugh .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of Julianne F. Haugh nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY JULIE HAUGH AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL JULIE HAUGH OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .TH PWAUTH 3 .SH NAME pwauth \- administrator defined password authentication routines .SH SYNTAX .B #include .PP .B int pw_auth (char .I *command, .B char .I *user, .B int .I reason, .B char .IB *input) ; .SH DESCRIPTION .B pw_auth invokes the administrator defined functions for a given user. .PP \fIcommand\fR is the name of the authentication program. It is retrieved from the user's password file information. The string contains one or more executable file names, delimited by semi\-colons. Each program will be executed in the order given. The command line arguments are given for each of the reasons listed below. .PP \fIuser\fR is the name of the user to be authenticated, as given in the \fI/etc/passwd\fR file. User entries are indexed by username. This allows non\-unique user IDs to be present and for each different username associated with that user ID to have a different authentication program and information. .PP Each of the permissible authentication reasons is handled in a potentially differenent manner. Unless otherwise mentioned, the standard file descriptors 0, 1, and 2 are available for communicating with the user. The real user ID may be used to determine the identity of the user making the authentication request. \fIreason\fR is one of .IP \fBPW_SU\fR 1i Perform authentication for the current real user ID attempting to switch real user ID to the named user. The authentication program will be invoked with a \fB\-s\fR option, followed by the username. .IP \fBPW_LOGIN\fR 1i Perform authentication for the named user creating a new login session. The authentication program will be invoked with a \fB\-l\fR option, followed by the username. .IP \fBPW_ADD\fR 1i Create a new entry for the named user. This allows an authentication program to initialize storage for a new user. The authentication program will be invoked with a \fB\-a\fR option, followed by the username. .IP \fBPW_CHANGE\fR 1i Alter an existing entry for the named user. This allows an authentication program to alter the authentication information for an existing user. The authentication program will be invoked with a \fB\-c\fR option, followed by the username. .IP \fBPW_DELETE\fR 1i Delete authentication information for the named user. This allows an authentication program to reclaim storage for a user which is no longer authenticated using the authentication program. The authentication program will be invoked with a \fB\-d\fR option, followed by the username. .IP \fBPW_TELNET\fR 1i Authenticate a user who is connecting to the system using the \fBtelnet\fR command. The authentication program will be invoked with a \fB\-t\fR option, followed by the username. .IP \fBPW_RLOGIN\fR 1i Authenticate a user who is connecting to the system using the \fBrlogin\fR command. The authentication program will be invoked with a \fB\-r\fR option, followed by the username. .IP \fBPW_FTP\fR 1i Authenticate a user who is connecting to the system using the \fBftp\fR command. The authentication program will be invoked with a \fB\-f\fR option, followed by the username. The standard file descriptors are not available for communicating with the user. The standard input file descriptor will be connected to the parent process, while the other two output file descriptors will be connected to \fI/dev/null\fR. The \fBpw_auth\fR function will pipe a single line of data to the authentication program using file descriptor 0. .IP \fBPW_REXEC\fR 1i Authenticate a user who is connecting to the system using the \fIrexec\fR command. The authentication program will be invoked with a \fB\-x\fR option, followed by the username. The standard file descriptors are not available for communicating with the remote user. The standard input file descriptor will be connected to the parent process, while the other two output file descriptors will be connected to \fI/dev/null\fR. The \fBpw_auth\fR function will pipe a single line of data to the authentication program using file descriptor 0. .PP The last argument is the authentication data which is used by the .B PW_FTP and .B PW_REXEC reasons. It is treated as a single line of text which is piped to the authentication program. When the reason is .BR PW_CHANGE, the value of \fIinput\fR is the value of previous user name if the user name is being changed. .SH CAVEATS This function does not create the actual session. It only indicates if the user should be allowed to create the session. .PP The network options are untested at this time. .SH DIAGNOSTICS The \fBpw_auth\fR function returns 0 if the authentication program exited with a 0 exit code, and a non\-zero value otherwise. .SH SEE ALSO .BR login (1), .BR passwd (1), .BR su (1), .BR useradd (8), .BR userdel (8), .BR usermod (8) .SH AUTHOR Julianne Frances Haugh (jockgrrl@ix.netcom.com)