sia_ses_init(3)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)
SYNOPSIS
#include <sia.h> #include <siad.h>
int sia_ses_init(
SIAENTITY ** entityhdl,
int arg,
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 );
LIBRARY
Standard C library (libc.so and libc.a)
PARAMETERS
The argc and argv parameters are used by the underlying security mecha‐
nisms for things like generating audit records and initializing data‐
base 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 session is being requested by a remote sys‐
tem. If the request is from a remote system, the hostname parameter
points to a string containing the remote host information. If informa‐
tion 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.
The username parameter is be set to point to the name or string repre‐
senting the requesting user if this information is available. Otherwise
this parameter is set to NULL. This parameter is read only. The tty‐
name 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. 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. 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. 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_col‐
lect_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 sia_* routines.
The passkey parameter provides a precollected password to the
authentication routine. Set this parameter to NULL if no pass‐
word has been precollected. This parameter is read only.
DESCRIPTIONsia_ses_init()
The sia_ses_init() routine initializes SIA sessions. The routine allo‐
cates an entity handle structure and initializes various values in that
structure. It must be called before any of the other SIA session pro‐
cessing routines.
sia_ses_reauthent()
The sia_ses_reauthent() routine is used to revalidate a user's pass‐
word. 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 pro‐
cessing 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 pass‐
word 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 ses‐
sion that is already checked or authenticated. This routine checks sys‐
tem or mechanism wide parameters such as licensing or resource limita‐
tions. 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 struc‐
ture 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 secu‐
rity 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
SEE ALSOinitgroups(3), siad_ses_init(3), matrix.conf(4)
Security
sia_ses_init(3)
