Index Index for
Section 3
Index Alphabetical
listing for S
Bottom of page Bottom of
page		 

sia_become_user(3)


NAME

  sia_become_user - su routine for SIA (Security Integration Architecture)


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

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

  argc
      The argc and argv parameters are used by the underlying security
      mechanisms for things like generating 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.

  hostname
      The hostname parameter is used to determine if the session 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 DECnet 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.

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

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

  colinput
      The colinput parameter specifies whether the collection of input is
      allowed during this session. A "1" means yes and "0" means no. This
      parameter is read only.

  gssapi
      The gssapi pointer is for future expansion to utilize gss_api
      datatypes. It is not currently used and should be set to NULL. This
      parameter is currently read only.

  envp
      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
      style_flags are specified as one or more of the following, or'ed
      together.

      SIA_BEU_CLEARENV
	  Establish only a minimal environment for the user context.

      SIA_BEU_DOCHDIR
	  chdir() to user's home dir.

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

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

      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 mechanisms
  are in use.  This is specifically intended for daemons like sendmail 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 initialize 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 created. (From this point on, failures will attempt to
       restore the previous environment.)

    ·  If _CLEARENV is set, the old TERM environment variable 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 specified, 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
       specified, these changes will still be in effect after a failure
       return.)

    ·  The process priority is reset to the system default with
       setpriority(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 processing 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 _OKROOTDIR 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 ALSO

  sia_ses_init(3), siad_ses_init(3), siad_init(3), matrix.conf(4)

  Security

Index Index for
Section 3
Index Alphabetical
listing for S
Top of page Top of
page