exec_asuser

NAME

execl_asuser(), execlp_asuser(), execle_asuser(), execv_asuser(), execve_asuser(), execvp_asuser() - execute a file as another user

SYNOPSIS

#include <interix/security.h>
extern char **environ;

int execl_asuser (const struct usersec userdata, const char *path, const char *arg ...) int execlp_asuser (const struct usersec userdata, const char *file, const char *arg ...) int execle_asuser (const struct usersec userdata, const char *path, const char *arg ... char *const envp[]) int execv_asuser (const struct usersec userdata, const char *path, char *const argv[]) int execve_asuser (const struct usersec userdata, const char *path, char *const argv[], char *const envp[]) int execvp_asuser (const struct usersec userdata, const char *file, char *const argv[])

DESCRIPTION

The exec_asuser(2) family of functions replaces the current process image with a new process image, run as the user specified in the structure userdata. These functions do a similar job to the calls setuid()/exec() on a BSD or SVR4 system. However, they do not behave identically, so do not rely heavily on this analogy.

You should use these functions instead of setuid() and exec() if you can supply a user name and password when executing the file. This allows the calling program to run with lower privileges because setuid() can only be called by programs running under the SYSTEM account or the local or domain Administrator account. Also, a program executed using the exec_asuser() functions can access network resources if run using a domain account; this is not possible when setuid() is used to establish the privilege level of the program.

Except for the initial userdata argument, the arguments to the exec_asuser(2) functions are identical to the corresponding exec(2) functions; see that reference page for more details.

The first argument is a user security structure, struct usersec, which is defined in <interix/security.h>:

struct usersec { 
	char * user;  
	char * domain;  
	char * password;  
	int logontype; Defaults to 0 
	int logonprovider; Defaults to 0 
}; 

The new process image maintains the following attributes and resources:

Calling Process Attribute Behavior
Open file descriptors Remain open, unless close-on-exec flag FD_CLOEXEC is set
Directory streams Closed
Signals set to default action Set to default action
Signals set to be ignored Set to be ignored
Signals set to be caught Set to default action
Real user ID Determined by usersec
Real group ID Determined by usersec
Supplementary group ID Determined by usersec
Effective user ID Determined by usersec
Effective group ID Determined by usersec
Process ID Inherited
Parent process ID Inherited
Process group ID Inherited
Session membership Inherited
Time left until alarm clock signal Inherited
Current working directory Inherited
Root directory Inherited
File mode creation mask Inherited
Process signal mask Inherited
Pending signals Inherited

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 to chdir(2) after a call to exec_asuser(2), to a directory known to be permitted for the new identity.

If these functions fail, the uids and gids for the remainder of the process are unspecified. The uid and gid of the process may remain the same as before this function was called or may be changed to that of the user defined in the usersec structure.

RETURN VALUES

On success, the exec_asuser(2) functions don't return. If they fail, they set errno and return -1.

ERRORS

The exec_asuser functions can set errno to any of the following values:

[E2BIG]
The argument list was too long.
[EACCES]
Search permission was denied for a directory in the path or the new process image file wasn't executable.
[EINVAL]
The values for logontype or logonprovider were bad.
[ENAMETOOLONG]
Some component of path was greater than {NAME_MAX}, or the entire pathname exceeded {PATH_MAX}.
[ENOENT]
One or more components of path doesn't exist, or the path or file argument is an empty string.
[ENOEXEC]
For execl_asuser(2), execv_asuser(2), execle_asuser(2), and execve_asuser(2), the new process image file has the appropriate access permission, but is not in the proper format.
[ENOMEM]
Not enough memory to load the new process image.
[ENOTDIR]
Some component of the path prefix of path is not a directory.
[EPERM]
The user-domain-password combination is invalid.

SEE ALSO

authenticateuser(2)

exec(2)

fork(2)

setuid(2)