PWAUTH(3)

NAME
pwauth - administrator defined password authentication routines

SYNTAX
#include <pwauth.h>

int pw_auth (char *command, char *user, int reason, char *input);

DESCRIPTION
pw_auth invokes the administrator defined functions for a given user.

command 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.

user is the name of the user to be authenticated, as given in the /etc/passwd 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.

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. reason is one of

PW_SU
    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 -s option, followed by the username.

PW_LOGIN
    Perform authentication for the named user creating a new login session. The authentication program will be invoked with a -l option, followed by the username.

PW_ADD
    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 -a option, followed by the username.

PW_CHANGE
    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 -c option, followed by the username.

PW_DELETE
    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 -d option, followed by the username.

PW_TELNET
    Authenticate a user who is connecting to the system using the fBtelnet command. The authentication program will be invoked with a -t option, followed by the username.

PW_RLOGIN
    Authenticate a user who is connecting to the system using the rlogin command. The authentication program will be invoked with a -r option, followed by the username.

PW_FTP
    Authenticate a user who is connecting to the system using the ftp command. The authentication program will be invoked with a -f 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 /dev/null. The pw_auth function will pipe a single line of data to the authentication program using file descriptor 0.

PW_REXEC
    Authenticate a user who is connecting to the system using the rexec command. The authentication program will be invoked with a -x 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 /dev/null. The pw_auth function will pipe a single line of data to the authentication program using file descriptor 0.

The last argument is the authentication data which is used by the PW_FTP and PW_REXEC reasons. It is treated as a single line of text which is piped to the authentication program. When the reason is PW_CHANGE, the value of input is the value of previous user name if the user name is being changed.

CAVEATS
This function does not create the actual session. It only indicates if the user should be allowed to create the session.

The network options are untested at this time.

DIAGNOSTICS
The pw_auth function returns 0 if the authentication program exited with a 0 exit code, and a non-zero value otherwise.

SEE ALSO
login(1), passwd(1), su(1), useradd(8), userdel(8), usermod(8)

AUTHOR
Julianne Frances Haugh (jfh@tab.com)