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

siad_ses_init(3)


NAME

  siad_ses_init, siad_ses_authent, siad_ses_suauthent, siad_ses_reauthent,
  siad_ses_estab, siad_ses_launch, siad_ses_release - SIA session routines
  (Security Integration Architecture)


SYNOPSIS

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

  int siad_ses_init(
	  SIAENTITY ** entityhdl );

  int siad_ses_authent(
	  int (*collect)(),
	  SIAENTITY *entityhdl,
	  int siastat,
	  int mechind );

  int siad_ses_suauthent(
	  int (*collect)(),
	  SIAENTITY *entityhdl,
	  int siastat,
	  int mechind );

  int siad_ses_reauthent(
	  int (*collect)(),
	  SIAENTITY *entityhdl,
	  int siastat,
	  int mechind );

  int siad_ses_estab(
	  int (*collect)(),
	  SIAENTITY *entityhdl,
	  int siastat,
	  int mechind );

  int siad_ses_launch(
	  int (*collect)(),
	  SIAENTITY *entityhdl,
	  int siastat,
	  int mechind );

  int sia_ses_release(
	  SIAENTITY **entityhdl,
	  int mechind );


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.

      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 siad_* routines.

  siastat
      The siastat parameter is set to SIADFAIL until at least one security
      mechanism has returned a SIADSUCCESS response to sia_ses_authent(). It
      is then set to SIADSUCCESS. Security mechanisms use this parameter to
      determine whether vouching is possible.

  mechind
      The mechind parameter is the mechanism index for this call. This index
      can be used to set the mechanism specific data pointer array element in
      the SIAENTITY structure pointed to by entityhdl.


DESCRIPTION

  siad_ses_init()

  This routine is called by sia_ses_init() to initialize a session with
  respect to a mechanism. This call is used to check resources and subsystems
  associated with a security mechanism. The siad_ses_init() routine returns
  SIADFAIL if the security mechanism cannot initialize a session. Otherwise,
  SIADSUCCESS is returned.

  siad_ses_reauthent()

  This routine is called from the sia_ses_reauthent() to reauthenticate a
  session with respect to a specific security mechanism.  This processing is
  typically associated with the locking or unlocking of a terminal or
  workstation by a particular user. The siad_ses_reauthent() routine is only
  called after a siad_ses_init() call to setup the SIAENTITY structure.

  siad_ses_authent()

  This routine is called by sia_ses_authent() to authenticate a session with
  respect to a security mechanism. The current state, success or fail, is
  indicated by siastat. The entityhdl pointer is used to access arguments
  which have either been collected or derived from the session processing.
  The mechanism index, mechind, is used by each mechanism to determine where
  in the sequence of processing the mechanism is configured and which index
  is to be used for mechanism specific data area associated with the
  SIAENTITY structure. The collect argument allows the mechanism to prompt
  the user for additional information.

  Vouching can occur during the sia_ses_authent() processing.  The default
  local security mechanism, BSD, allows vouching and returns SIADSUCCESS if
  siastat is already set to SIADSUCCESS. (This indicates that some previously
  called security mechanism has successfully authenticated this entity.)

  siad_ses_suauthent()

  This routine is called from sia_ses_suauthent() to do su command mechanism
  dependent processing. Unlike the other session processing interfaces,
  generally only one of the mechanisms would be configured to process the su
  authentication. However, multiple mechanisms could be configured to do this
  processing. This routine is only called after a siad_ses_init() call has
  been made to create the SIAENTITY structure.

  siad_ses_estab()

  This routine is called by sia_ses_estab() and performs mechanism-specific
  processing associated with general resource and licensing checking. This
  routine also gathers all the required context needed to establish a
  session. For example, the local security mechanism requires that the struct
  passwd in the SIAENTITY structure be completed to successfully establish
  the session. The local mechanism may also use this routine to check the
  system limits to make sure this session does not exceed the configuration.

  siad_ses_launch()

  This routine is called from the sia_ses_launch() routine to do security
  mechanism specific logging or auditing in preparation of the session
  startup. The local security mechanism may have additional responsibilities
  such as tty conditioning or processing for wtmp and utmp. On the successful
  return from siad_ses_launch(), the local security mechanism sets the
  effective user ID (EUID) to the user requesting the session. The local
  mechanism sets the groups and group ID (GID) using the setgid() and
  initgroups() calls.

  siad_ses_release()

  The siad_ses_release() routine is called by the sia_ses_release() routine
  to release resources associated with the session processing which is now
  completed. The security mechanism is responsible for releasing any
  allocated memory which is no longer needed by this session.  If a security
  mechanism has allocated memory pointed to by the SIAENTITY structure, this
  memory must be deallocated at this time.


RETURN VALUES

  The siad_ses_*() routines return bitmapped values which indicate the
  following status:

  SIADSUCCESS
      Indicates unconditional success. All bits set to 0.

  SIADFAIL
      Indicates conditional failure. Lowest bit set to 1. If other security
      mechanism are in place, continue.

  SIADSTOP
      Indicates unconditional failure. Do not continue. Second lowest bit set
      to 1.


ERRORS

  The errno values are those returned from the dynamic loader interface, from
  the (siad_*) routines, or from malloc. Possible errors include resource
  constraints (no memory) and various authentication failures.


FILES

  /etc/group

  /etc/passwd

  /etc/sia/matrix.conf


SEE ALSO

  setgid(2), initgroups(3), sia_ses_init(3), matrix.conf(4)

  Security

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