shadow/man/pw_auth.3

.\"$Id: pw_auth.3,v 1.9 2004/12/11 20:05:01 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 <pwauth.h>
.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)