Index for Section 3

Alphabetical listing for S

Bottom of page

sia_ses_init(3)
NAME
  sia_ses_init,	 sia_ses_authent,  sia_ses_suauthent, sia_ses_reauthent,
  sia_ses_estab, sia_ses_launch, sia_ses_release - SIA session routines
  (Security Integration Architecture)

LIBRARY
  Standard C library (libc.so and libc.a)

SYNOPSIS
  #include <sia.h>
  #include <siad.h>

  int sia_ses_init(
	  SIAENTITY ** entityhdl,
	  int argc, char **argv,
	  char *hostname,
	  char *username,
	  char *ttyname,
	  int can_collect_input,
	  char *gssapi);

  int sia_ses_authent(
	  int (*collect)(),
	  char *passkey,
	  SIAENTITY *entityhdl);

  int sia_ses_suauthent(
	  int (*collect)(),
	  SIAENTITY *entityhdl);

  int sia_ses_reauthent(
	  int (*collect)(),
	  SIAENTITY *entityhdl);

  int sia_ses_estab(
	  int (*collect)(),
	  SIAENTITY *entityhdl);

  int sia_ses_launch(
	  int (*collect)(),
	  SIAENTITY *entityhdl);

  int sia_ses_release(
	  SIAENTITY **entityhdl);

PARAMETERS
  argc and argv
	      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.

  ttyname     The ttyname parameter is set to point to the name or string
	      representing the requesting or active tty if this information
	      is available.  Otherwise this parameter is set to NULL.  This
	      parameter is read only.

  can_collect_input
	      The can_collect_input 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.

  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.

	      Further input on SIA collection routines is available from the
	      interface specifications in /usr/include/{sia,siad}.h.

  entityhdl   The entityhdl parameter points to the SIAENTITY structure that
	      was allocated and setup by the previous sia_ses_init() call.
	      Values in the SIAENTITY structure may be changed by the sia_*
	      routines.

  passkey     The passkey parameter provides a precollected password to the
	      authentication routine. Set this parameter to NULL if no
	      password has been precollected.  This parameter is read only.

DESCRIPTION
  sia_ses_init()

  The sia_ses_init() routine initializes SIA sessions.	The routine allocates
  an entity handle structure and initializes various values in that
  structure.  It must be called before any of the other SIA session
  processing routines.




  sia_ses_reauthent()

  The sia_ses_reauthent() routine is used to revalidate a user's password.
  It is associated with applications that require that the user be
  reauthenticated.  Such applications are the typical terminal or session
  locking applications.	 This call must be preceded by a call to
  sia_ses_init() and followed by a call to sia_ses_release().

  sia_ses_release()

  The sia_ses_release() routine is called at the end of the session
  processing to release any resources associated with the session startup
  processing, including the SIAENTITY structure.  After calling the
  sia_ses_release() routine, do the setuid and then exec the program to start
  the actual new process running as the session user ID.

  sia_ses_authent()

  The sia_ses_authent() routine is called to authenticate an entity.  Since
  this routine may require parameter collection, a collect routine pointer is
  provided by the calling application. It is also possible that the password
  has been pre-collected by the application (such as, ftp). The passkey
  parameter allows the application to provide a password to the security
  mechanisms.  Providing a passkey is not sufficient to keep the underlying
  mechanisms from trying to prompt for additional information.	The
  sia_ses_init() routine must be called before calling this routine.

  sia_ses_suauthent()

  The sia_ses_suauthent() routine processes the su command. Since the
  processing of the  su command is viewed as special and may require an
  alternative configuration from the normal sia_ses_authent() routine, it has
  been made a separate SIA capability. Like the sia_ses_authent() routine
  sia_ses_suauthent is preceded by a call to sia_ses_init() and followed by a
  call to sia_ses_release().

  sia_ses_estab()

  The sia_ses_estab() routine is called to establish context for a session
  that is already checked or authenticated. This routine checks system or
  mechanism wide parameters such as licensing or resource limitations. The
  sia_ses_estab() routine also collects the complete set of information or
  context required to launch a session.	 However, for a login model the
  environment processing (clearenv() and setenv()) must still be done.	Copy
  any HOME or SHELL strings from the SIAENTITY structure because the final
  call to sia_ses_release() will free the entire SIAENTITY structure.  If the
  sia_ses_estab() routine fails, sia_ses_release() is automatically called.

  sia_ses_launch()

  The sia_ses_launch() routine is called to do the final processing of a
  session before the actual start of the session by the application. This
  processing usually consists of the logging or auditing the session startup
  and any tty conditioning which may be required. Not all security mechanisms
  may require processing at this time. Generally, the local mechanism is
  required to do the launch processing.	 If the sia_ses_launch() routine
  fails, sia_ses_release() is automatically called.

  On the return from sia_ses_launch(), the effective UID (EUID) has been set
  to the UID of the user for this session.  Generally, a
  setreuid(geteuid(),geteuid()) follows this return setting both the real
  user ID (RUID) and effective user ID (EUID) to the effective user ID
  (EUID). The remaining processing is utility dependent.

  All the users group memberships are set using initgroups().

RETURN VALUES
  The sia_ses_*() routines return SIASUCCESS when the are successful and
  SIAFAIL when they are not successful.


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/passwd

  /etc/group

  /etc/sia/matrix.conf

RELATED INFORMATION
  initgroups(3), siad_ses_init(3), matrix.conf(4)

  Security

Index for Section 3

Alphabetical listing for S

Top of page