sia_become_user(3)sia_become_user(3)NAMEsia_become_user - su routine for SIA (Security Integration Architec‐
ture)
SYNOPSIS
#include <sia.h> #include <siad.h>
int sia_become_user(
sia_collect_func_t *collect,
int argc,
char **argv,
char *hostname,
char *username,
char *tty,
int colinput,
char *gssapi,
char **envp,
int style_flags );
LIBRARY
Standard C library (libc.so and libc.a)
PARAMETERS
The collect parameter is a pointer to an SIA collection routine. If
this pointer is NULL, no collection is possible. If the pointer is not
NULL and the can_collect_input parameter entered during the
sia_ses_init() call was zero, then this collection routine cannot be
used to prompt for input but can be used to display warnings or error
messages. This parameter is read only. The argc and argv parameters
are used by the underlying security mechanisms for things like generat‐
ing audit records and initializing database accesses. There should
always be at least one argument argv[0] which contains the name of the
command or utility issuing a session initialization. These parameters
are read only. The hostname parameter is used to determine if the ses‐
sion is being requested by a remote system. If the request is from a
remote system, the hostname parameter points to a string containing the
remote host information. If information about the requesting remote
user is available, the information is in the form "node::user" for DEC‐
net or "user@host" for IP. If the remote user information is not
available, the information is the remote "host". For local requests,
this parameter is passed as a NULL pointer. The username parameter is
be set to point to the name or string representing the requesting user
if this information is available. Otherwise this parameter is set to
NULL. This parameter is read only. The tty parameter is set to point
to the name or string representing the requesting or active tty or X
display if this information is available. Otherwise this parameter is
set to NULL. This parameter is read only. The colinput parameter spec‐
ifies whether the collection of input is allowed during this session. A
"1" means yes and "0" means no. This parameter is read only. The gss‐
api pointer is for future expansion to utilize gss_api datatypes. It is
not currently used and should be set to NULL. This parameter is cur‐
rently read only. The envp parameter specifies the environment array
to add to the environment established for the environment. Refer to
exec(2) for a description of environment arrays. style_flags are spec‐
ified as one or more of the following, or'ed together. Establish only
a minimal environment for the user context. chdir() to user's home
dir. chdir() to "/" is the user's home directory is not available.
This flag is ignored unless SIA_BEU_DOCHDIR or SIA_BEU_REALLOGIN is
also set. This is a full login, in the style of rlogind or rshd,
rather than a 'su -user' equivalent.This flag implies SIA_BEU_DOCHDIR
and SIA_BEU_SETLUID. Set or change the audit ID of the process and
call setlogin().
DESCRIPTION
This routine allows a privileged process to establish the full set of
credentials for a specified user, for whichever system security mecha‐
nisms are in use. This is specifically intended for daemons like send‐
mail and cron which frequently have to perform unknown operations on
behalf of a given user.
The order of operations for this routine are as follows: (Note that in
all cases, operations that fail cause succeeding steps to be skipped
and the function returns SIAFAIL.) sia_ses_init() is called to ini‐
tialize the SIA session. The argc through gssapi arguments are used.
getpwnam_r() is called for the specified username.
sia_make_entity_pwd() is called to complete filling out the SIA entity
structure. If _REALLOGIN is set, the entity's authtype field is set to
SIA_A_NONE and sia_ses_estab() is called. If _REALLOGIN is not set, the
entity's authtype field is set to SIA_A_SUATH. If _CLEARENV is set,
the pointer to the old_environ is saved and a new (empty) one is cre‐
ated. (From this point on, failures will attempt to restore the previ‐
ous environment.) If _CLEARENV is set, the old TERM environment vari‐
able will be propagated to the new environment (as is also done by
login(1)) and a PATH environment variable is set to the value
"/usr/bin:". The LOGNAME, USER, SHELL, and HOME environment variables
are set from the user's profile. (Caution: If _CLEARENV was not speci‐
fied, these changes will still be in effect after a failure return) If
the 'envp' variable is non-NULL, each entry in that list is added to
the environment with putenv(). (Caution: If _CLEARENV was not speci‐
fied, these changes will still be in effect after a failure return.)
The process priority is reset to the system default with setprior‐
ity(PRIO_PROCESS, 0, 0). If _SETLUID was set and _REALLOGIN was not,
the process audit ID is changed and setlogin() is called. If _REALLOGIN
was set, these steps are performed by sia_ses_estab() and
sia_ses_launch(). sia_ses_launch() is called to perform the final pro‐
cessing of the session. This step will also call initgroups() if it is
successful, or in some cases if it is not successful. This change in
the supplementary groups of the process is not restored on subsequent
failure. If _DOCHDIR was set and _REALLOGIN was not, an attempt is
made to chdir to the user's home directory. If that fails and _OKROOT‐
DIR was not set, or if the chdir("/") fails, SIAFAIL is returned. If
_REALLOGIN was set and _OKROOTDIR was not, and if the user's home
directory was not "/", a check is made to see whether sia_ses_launch()
did a chdir("/") because the user's home directory was not available.
If that is the case, SIAFAIL is returned. sia_session_release() is
called.
RETURN VALUES
The sia_become_user() routine returns either SIASUCCESS or SIAFAIL.
ERRORS
The errno value is not (normally) set explicitly by sia_* routines. The
errno values are those returned from the dynamic loader interface, from
dependent (siad_*) routines, or from malloc. Possible errors include
resource constraints (no memory) and various authentication failures.
FILES
/etc/sia/matrix.conf
SEE ALSOsia_ses_init(3), siad_ses_init(3), siad_init(3), matrix.conf(4)
Security
sia_become_user(3)
