setuser

NAME

setuser() - change effective and real uid and gid of process

SYNOPSIS

#include <interix/security.h>


int setuser(char *username, char *password, int flags)

The setuser(2) function changes the effective and real uid and gid of the current process to that of the specified username. All of the security attributes and permissions become those of username. However, the process' current working directory does not change.

The setuser(2) function takes the following arguments:

username

The name of the user.

password

The plaintext password for the specified username. The password is not needed if the security ID of the calling process is one of SYSTEM, local+Administrator (where local is the name of the local domain), or pdomain+Administrator (where pdomain is the name of the principal domain). In this case, password can be passed as the NULL pointer.

flags

Control flags. These possible values for flags are defined in <interix/security.h>:

SU_COMPLETE: Change the real and effective user and group IDs and all security attributes to the default for the specified user.
SU_CHECK: Check that the process will be able to perform a setuser(2) action using SU_COMPLETE for the specified username and password. This is a quick way to verify a password for a user. This action is equivalent to the older INTERIX call, authenticateuser(2).

There can be a performance degradation if a process changes identity to a user who does not have permission to be located in the current working directory. The best solution is, after a call to setuser(2), to chdir(2) to a directory known to be permitted for the new identity.

You must have the right to log on interactively on a domain controller for someone to call setuser(2) for you. An administrator, however, can call setuser(2) for you even if you do not have the right to log on interactively to a domain controller. If the administrator calls setuser(2) for you, he or she is not required to use your password.

RETURN VALUE

On success, the setuser(2) function returns 0. On failure, it returns -1 and sets errno.

ERRORS

The setuser(2) function can fail for the following reasons:

[ENOMEM]: Not enough memory to complete the request.
[EINVAL]: An argument is invalid or is missing.
[EPERM]: The requesting process does not have permission to change to the new user. Either or both of the username or password were incorrectly specified.

NOTES

This function replaces authenticateuser(2). In fact, the version of authenticateuser(2) in this release is a wrapper around setuser(2).