siad_ses_init(3)siad_ses_init(3)NAME
siad_ses_init, siad_ses_authent, siad_ses_suauthent, siad_ses_reau‐
thent, 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
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. 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_* rou‐
tines. 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 mech‐
anisms use this parameter to determine whether vouching is pos‐
sible. 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.
DESCRIPTIONsiad_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 sub‐
systems associated with a security mechanism. The siad_ses_init() rou‐
tine 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 struc‐
ture.
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 config‐
ured 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 authen‐
ticated this entity.)
siad_ses_suauthent()
This routine is called from sia_ses_suauthent() to do su command mecha‐
nism dependent processing. Unlike the other session processing inter‐
faces, 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-spe‐
cific processing associated with general resource and licensing check‐
ing. 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 suc‐
cessfully 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 responsibili‐
ties 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 set‐
gid() and initgroups() calls.
siad_ses_release()
The siad_ses_release() routine is called by the sia_ses_release() rou‐
tine 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: Indicates unconditional success. All bits set to 0.
Indicates conditional failure. Lowest bit set to 1. If other security
mechanism are in place, continue. 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 ALSOsetgid(2), initgroups(3), sia_ses_init(3), matrix.conf(4)
Security
siad_ses_init(3)
