ph_login(3)

NAME
ph_login, ph_logout, ph_suser - PH server authentication routines

SYNOPSIS
#include <phclient.h>

int ph_login(PH *ph, char *alias, int authtype, void *auth);
int ph_logout(PH *ph);
int ph_suser(PH *ph, char *alias);
int ph_passwd(PH *ph, char *newpass);
char *ph_whoami(PH *ph);

VERSION
This man page documents version 1.2 of libphclient.

DESCRIPTION
The ph_login() function authenticates the user alias to the PH server associated with the PH handle ph. The authtype argument must be set to one of the following values:

PH_AUTH_EMAIL
    Email authentication. If the connection was established using the PH_OPEN_PRIVPORT flag to ph_open(), the user will be authenticated if the local username and hostname match the value of the user's email field on the PH server. The auth argument is ignored.

PH_AUTH_PASSWORD
    Encrypted password authentication. The auth argument is the user's password.

PH_AUTH_CLEAR
    Cleartext password authentication. Use of this authentication method is not recommended, since it is inherently insecure. The auth argument is the user's password.

The ph_logout() function logs the currently logged-in user out of the PH server. The session goes back to being an unpriveledged, anonymous session. The ph_suser() function allows a PH hero to assume the identity of any arbitrary user without hero priveledges. The alias argument indicates the user whose priveledges should be assumed. The ph_passwd() function changes the password of the currently logged-in user. The newpass argument is the new password. The ph_whoami() function returns the name of the currently logged-in user, or NULL if no user is logged in.

RETURN VALUE
On successful completion, ph_login() returns 0. If authentication is denied by the server, it returns PH_ERR_NOTLOG. On failure, it returns -1 and sets errno to an appropriate value. On successful completion, ph_logout() returns 0. If no user is logged in, it returns PH_ERR_NOTLOG. On other errors, it returns -1 and sets errno to an appropriate value. The ph_suser() function returns 0 on success, PH_ERR_NOTHERO if the calling user is not a PH hero, or PH_ERR_NOTLOG if no user is logged in. On failure, it returns -1 and sets errno to an appropriate value. The ph_passwd() function returns 0 on success, or PH_ERR_NOTLOG if no user is logged in. It can also fail with the same values returned by ph_change(3). On failure, it returns -1 and sets errno.

ERRORS
The functions described here may fail with any error from the functions read() or write(). The ph_login() function will return the following errors:

EINVAL
    The authtype is invalid.

EINVAL
    Invalid data is read from the server.

EAGAIN
    The server responds with a temporary failure.

In addition, ph_login() may fail with any error from the functions getpwuid() or malloc().

SEE ALSO
read(2), write(2), getpwuid(3), ph_open(3), ph_change(3)