si_library(3) DG/UX B2 Security R4.12MU02 si_library(3)
NAME
dgsirequestandgetsessioninfo, dgsisetsessionmode,
dgsidestroysessioninfo, dgsikitcreate, dgsirequest,
dgsigetnextaction, dgsirespondtoaction,
dgsigetsessioninfo, dgsikitdestroy, dgsigeterrmsg -
session initiator routines in libsm.a
SYNOPSIS
#include <dgsiinterface.h>
int dgsirequestandgetsessioninfo(
dgsiinfot *siinfop, /* READ */
char *reqservice, /* READ */
char *requser, /* READ */
char *reqmacalias, /* READ */
maclabelt reqmaclabel, /* READ */
char *location, /* READ */
char *locale, /* READ */
dgobjectattrstype *deviceattrsp, /* READ */
dgseccredt *oldcredp, /* READ */
dgsiactionfcnt actionfcn, /* EXECUTE */
void *actionfcnarg, /* READ */
dgsisessioninfot *sessioninfop /* WRITE */
)
int dgsisetsessionmode(
dgsisessioninfot *sessioninfop, /* READ */
dgsisessionmodet sessionmode /* READ */
)
int dgsidestroysessioninfo(
dgsisessioninfot *sessioninfop /* READ/WRITE */
)
int dgsikitcreate(
dgsiinfot *siinfop, /* READ */
char *reqservice, /* READ */
char *requser, /* READ */
char *reqmacalias, /* READ */
char *reqmaclabel, /* READ */
char *location, /* READ */
char *locale, /* READ */
dgobjectattrstype *deviceattrsp, /* READ */
dgseccredt *oldcredp, /* READ */
dgsikithandlet *sikithandlep /* WRITE */
)
int dgsirequest(
dgsikithandlet sikithandle, /* READ */
dgsiactionfcnt actionfcn, /* EXECUTE */
void *actionfcnarg /* READ */
)
int dgsigetnextaction(
dgsikithandlet sikithandle, /* READ */
dgsitousrt *tousrp /* WRITE */
)
int dgsirespondtoaction(
dgsikithandlet sikithandle, /* READ */
dgsifromusrt *fromusrp /* READ */
)
int dgsigetsessioninfo(
dgsikithandlet sikithandle, /* READ */
dgsisessioninfot *sessioninfop /* WRITE */
)
int dgsikitdestroy(
dgsikithandlet *sikithandlep /* READ/WRITE */
)
char *dgsigeterrmsg(void)
DESCRIPTION
This manual page describes the session initiator routines in libsm.a.
These routines are layered so as to provide varying levels of control
and ease-of-programming.
The highest level routines are dgsirequestandgetsessioninfo,
dgsisetsessionmode, dgsidestroysessioninfo, and
dgsigeterrmsg. Many session initiators will only need to use
these routines; however, lower level routines are available if
required.
The dgsirequestandgetsessioninfo routine is implemented very
simply by calling the following lower level routines (in order):
dgsikitcreate, dgsirequest, dgsigetsessioninfo, and
dgsikitdestroy. If a session initiator needs to perform an
intermediate step, these lower level routines can be called directly.
At the lowest level are the routines: dgsigetnextaction and
dgsirespondtoaction. The dgsirequest routine is implemented
using these routines.
dgsirequestandgetsessioninfo
This routine issues a session request and, if successful, returns
session information. This routine does not change the caller's
credentials or environment; it simply returns what the credentials
and environment for the session should be.
siinfop points to session-initiator-specific information; see the
SESSION INITIATOR INFO section below for more information.
reqservice is the name of the requested service. requser is the
username of the requested session. reqmacalias or reqmaclabel
specify the MAC label of the requested session. At least one of
these parameters must be NULL; if both are NULL, the default MAC
label for the session is requested. location identifies the physical
location of the person making the request. locale is the locale of
the requested session. deviceattrsp is a pointer to the device's
object attributes through which the request is being made; the MAC
label and range (or tuple) of the requested session are limited by
deviceattrsp. oldcredp is the credentials of the client making
the session request; this parameter should be NULL if the client has
no credentials. actionfcn and actionfcnarg are used to perform
any actions required before the session request can be granted; see
the ACTION FUNCTIONS section below for more information.
sessioninfop is a pointer to the structure that is filled in upon
successful return from this routine.
Return values:
0 Authentication was successful and the session information is
filled in.
-1 An error occurred.
dgsisetsessionmode
This routine sets the credentials on the calling process according to
the session information in sessioninfop and sessionmode.
sessioninfop must have been filled in by a successful call to
dgsirequestandgetsessioninfo or dgsigetsessioninfo.
If sessionmode equals SiSModeUser, the credentials are set so that
the current process has no extra privilege; however, the process may
still have the ability to obtain extra privilege in order to perform
system operations as required by some session initiators, or to pass
extra privilege along to another process.
If sessionmode equals SiSModeUserExec, the credentials are set so
that the current process runs completely with the user's credentials;
once the session is in this mode, it may not be possible to set to
another session mode.
If sessionmode equals SiSModeSystemExec, the current process passes
any additional system privileges across an exec system call. This
mode should be used after a fork but before an exec.
Return values:
0 The session mode was successfully set as requested.
-1 An error occurred and the session mode was not set as
requested.
dgsidestroysessioninfo
This routine destroys the session information pointed to by
sessioninfop.
Return values:
0 The session information was successfully destroyed.
-1 An error occurred.
dgsikitcreate
This routine creates a session initiator kit, which is required as a
parameter to other silibrary routines. siinfop points to session-
initiator-specific information; see the SESSION INITIATOR INFO
section below for more information. reqservice is the name of the
requested service. requser is the user name of the requested
session. reqmacalias or reqmaclabel specify the MAC label of the
requested session. At least one of these parameters must be NULL; if
both are NULL, the default MAC label for the session is requested.
location identifies the physical location of the person making the
request. locale is the locale of the requested session.
deviceattrsp is a pointer to the device's object attributes through
which the request is being made; the MAC label and range (or tuple)
of the requested session are limited by deviceattrsp. oldcredp
is the credentials of the client making the session request; this
parameter should be NULL if the client has no credentials.
sikithandlep is a pointer to a kit handle that is set upon
successful return from this routine.
Return values:
0 The session initiator kit was successfully created and
*sikithandlep was set to the kit handle.
-1 An error occurred.
dgsirequest
This routine issues a session request and returns success or failure
for the request. sikithandle is the kit handle (as set by
dgsikitcreate). actionfcn and actionfcnarg are used to perform
any actions required before the session request can be granted; see
the ACTION FUNCTIONS section below for more information.
Return values:
0 Authentication was successful.
-1 An error occurred in dgsirequest.
Else A non-zero value was returned by actionfcn, indicating a
failure to perform the action.
dgsigetnextaction
This routine gets the next action for the session initiator to
perform. The first call returns the first action to perform.
sikithandle is the kit handle (as set by dgsikitcreate). Upon
successful return from this routine, the structure pointed to by
tousrp is filled in with the appropriate information specifying the
action to perform. The set of possible actions is defined by the
dgsitousrcluee enumerated type in <dgsiinterface.h>.
Return values:
1 A non-terminal action was successfully returned; a non-
terminal action is a DGSIACTION... value of the
dgsitousrcluee enumerated type (in <dgsiinterface.h>).
0 A terminal action was successfully returned; a terminal action
is a DGSIRETURN... value of the dgsitousrcluee
enumerated type (in <dgsiinterface.h>).
-1 An error occurred in dgsigetnextaction.
dgsirespondtoaction
This routine is called to respond to a non-terminal action as
returned by the previous call to dgsigetnextaction. A non-
terminal action is a DGSIACTION... value of the
dgsitousrcluee enumerated type (in <dgsiinterface.h>).
sikithandle is the kit handle (as set by dgsikitcreate).
fromusrp points to the response information from the user. For
example, if the last action that the session initiator was told to
perform was DGSIACTIONGETPASSWD, the fields in the fromusrp
structure should be set as follows prior to calling this routine:
rsvp equals DGSIFROMUSEROKAY, and datap points to the first
octet of and datal is the number of octets in the password provided
by the user (including the null octet which, terminates the string).
Return values:
0 The response was successful.
-1 An error occurred.
dgsigetsessioninfo
This routine gets the information for a session that has already been
granted via dgsirequest. sikithandle is the kit handle (as set
by dgsikitcreate) and corresponds to a successful session request;
sessioninfop is a pointer to the structure that is filled in upon
successful return from this routine.
Return values:
0 The session information was successfully obtained.
-1 An error occurred.
dgsikitdestroy
This routine destroys a session initiator kit. sikithandlep is a
pointer to a session initiator kit that was successfully set by
dgsikitcreate.
Return values:
0 The session initiator kit was successfully destroyed.
-1 An error occurred.
dgsigeterrmsg
If a failure occurs in any of the silibrary routines, this routine
returns a message describing the error that occurred. If no error
has occurred, this routine returns a pointer to an empty string, not
NULL.
Return values:
A string describing the error that occurred.
SESSION INITIATOR INFORMATION
This section describes the fields of the dgsiinfot structure
containing session-initiator-specific information.
The version field must be set to SiInfoVersion1.
The mergeops field defines the policy for combining the client's
credentials with the new credentials to create the resulting
session's credentials. The client's credentials need not be used at
all, in which case each field should be set to the UseNew... value
for the corresponding enumerated type. Alternatively, the client's
credentials may be used to restrict the new credentials. For
example, the mergeops.macrangeop field can be set to
IntersectMacRangeOp in order to make sure that the MAC range (or
tuple) cannot be any larger than the client's MAC range (or tuple).
Similarly, the mergeops.capop field can be set to IntersectCapOp in
order to make sure that the client's resulting session does not have
any more capabilities than the previous session. If the
mergeops.auditmaskop field is set to UnionAuditMaskOp, this
insures that the audit mask can only grow. The
mergeops.authinfoop field can be set to PushAuthInfoOp to push the
new authentication information on the old stack, or to
PopAndPushAuthInfoOp, which pops the old authentication information
and then pushes the new on the old.
The systemevents field contains a list of events that this session
initiator performs as system or user-augmented operations.
The options field contains all the session-initiator options to use
during authentication. Each option requests a special behavior from
the credential server (credentiald(1)) during the session initiation
process. It will only honor the option if the requestor has
appropriate privilege. If the requestor fails the privilege check,
the option is silently ignored. Even if an option is set and
appropriate privilege exists, the credential server still enforces
all other session initiation requirements other than the one affected
by the option. More than one option at a time may be turned on,
although each must still pass an appropriate privilege check. There
are several options defined in dgsioptionst which are not
described here. Those options are for future use, and are currently
unimplemented. If set, they will be ignored. The function of the
various options is as follows:
noauthentication
If set, this option indicates that the user should be allowed to
create a session without being required to authenticate.
bypasslocationlocked
If set, this option indicates that the user should be allowed to
create a session even if the specified location is locked.
bypassaccountextinct
If set, this option indicates that the user should be allowed
to create a session even if the account is extinct-- that is,
even if the account is older than the lifetime specified for
it by the administrator.
bypassaccountlocked
If set, this option indicates that the user should be allowed
to create a session even if the account is locked. The
account my be locked either by administrative action or
automatically by the system due to repeated invalid session
initiation attempts.
bypassaccountstale
If set, this option indicates that the user should be allowed
to create a session even if the account is stale-- that is,
even if the account has been unused for longer than the time
allowed by the system administrator.
ACTION FUNCTIONS
An action function is called to perform actions that are required
before a session request can be granted. Since only the session
initiator knows how to perform these actions (e.g., to get a password
from the user), each session initiator provides its own action
function. The interface for an action function is as follows.
int actionfcn(
dgsikithandlet sikithandle, /* READ */
dgsitousrt *tousrp, /* READ */
dgsifromusrt *fromusrp, /* WRITE */
void *actionfcnarg /* READ */
)
sikithandle is the handle for the session initiator kit. This
parameter is not currently used by an action function.
tousrp points to the information denoting the action to be
performed. The clue field is the action to perform and can be any
non-terminal action required before the session request can be
granted; all terminal actions are handled by dgsirequest (and
therefore by dgsirequestandgetsessioninfo). The set of non-
terminal actions are defined to be those actions that require a
response from the session initiator; in particular, they are any of
the DGSIACTION... values of the dgsitousrcluee enumerated
type (in <dgsiinterface.h>). The set of terminal actions are those
actions that do not require a response; they are any of the
DGSIRETURN... values of the dgsitousrcluee enumerated type.
fromusrp points to the structure that must be filled in by the
action function before returning and is used to return the response
to the action request. For example, if the last action that the
session initiator was told to perform was DGSIACTIONGETPASSWD,
the fields in the fromusrp structure should be set as follows prior
to returning from the action function: rsvp equals
DGSIFROMUSEROKAY, and datap points to the first octet of and
datal is the number of octets in the password provided by the user
(including the null octet, which terminates the string). The rsvp
field should always be set to DGSIFROMUSEROKAY if the action
function successfully completed the action; otherwise, it is set to
indicate the reason for the failure. The datap and datal should be
set to indicate the location and length of any data being passed back
as part of the response; be sure that datap does not point to a
stack variable since it is not available upon return from the action
function. If there is no data to return, these fields need not be
set.
actionfcnarg is the pointer that was passed to
dgsirequestandgetsessioninfo or to dgsirequest.
Return values:
0 The requested action was successfully performed.
< 0 A failure occurred when trying to perform the requested action
and an error message should be set for retrieval by a call to
dgsigeterrmsg.
> 0 A failure occurred when trying to perform the requested action
and an error message should not be set.
EXAMPLES
The following is a sample program for a typical session initiator
that uses several of the silibrary routines.
#include <stdio.h>
#include <unistd.h>
#include <syslog.h>
#include <dg_sec_subject.h>
#include <dg_si_interface.h>
/*
* The following is session-initiator-specific information.
* (1) The "merge operations" define the method that this
* session initiator uses to calculate the credentials
* for the target session given the client's
* credentials (if any) and the new session.
* For example, this session initiator limits the target
* session's MAC range (or tuple) and capabilities by
* intersecting those from the client. The UseOldOrNewAuthIdOp
* specifies that if the old auth-ID is non-null, use it;
* otherwise, use the new auth-ID (which must then be
* non-null);
* (2) The system_caps are the caps that this session
* initiator performs as system or user-augmented operations.
* (3) The "options" are various options that the session initiator
* may choose with regard to how authentication is
* performed.
*/
static dg_si_info_t si_info =
{
SiInfoVersion1,
{ /* merge operations */
UseOldOrNewAuthIdOp,
UseNewCredOp,
UseNewMacLabelOp,
IntersectMacRangeOp,
IntersectCapOp,
UnionAuditMaskOp,
PushAuthInfoOp
},
NULL, /* no system caps required */
{ /* options */
0, /* no_authentication */
0, /* weak_authentication */
0, /* bypass_location_locked */
0, /* bypass_account_extinct */
0, /* bypass_account_locked */
0, /* bypass_account_stale */
0, /* bypass_qru_extinct */
0, /* bypass_qru_locked */
0 /* bypass_qru_expired */
}
};
/*
* Session initiator authentication action function.
* This action function performs all actions possible
* to perform authentication (i.e. to grant a session
* request).
*/
int action_fcn(
dg_si_kit_handle_t si_kit_handle, /* READ */
dg_si_to_usr_t *to_usr_p, /* READ */
dg_si_from_usr_t *from_usr_p, /* WRITE */
void *action_fcn_arg /* READ */
)
{
if( to_usr_p->clue == DG_SI_ACTION_GET_PASSWD )
{
char *passwd;
size_t passwd_len;
/*
* Get the password from the user and set
* 'passwd' and 'passwd_len' appropriately.
*/
from_usr_p->rsvp = DG_SI_FROM_USER_OKAY;
from_usr_p->data_p = passwd;
from_usr_p->data_l = passwd_len;
return(0); /* return successfully */
}
/*
* This action function doesn't support any other
* actions. Return a value less than 0 so that
* the si_library routine stores an error message
* describing which action failed; return -2 instead
* of -1 just in case I need to disambiguate between
* a failure here and a failure in the SI library.
*/
from_usr_p->rsvp = DG_SI_FROM_USER_REFUSED;
return(-2);
} /* end action_fcn */
/*
* Authenticate.
* If successful, set the credentials and return;
* otherwise, exit after syslogging an error message.
*/
void authenticate_and_set_credentials(void)
{
char *user;
char *mac_alias;
char *location;
char *locale;
dg_sec_cred_t *client_cred_p;
dg_si_session_info_t session_info;
/*
* Set all of the variables above to their
* appropriate values.
*/
/*
* Make the session request; 'action_fcn' will
* perform any actions required before this request
* can be granted; and if the request is granted,
* return the session information.
*/
if( dg_si_request_and_get_session_info(
&si_info,
"the_service_name",
user,
mac_alias, /* request MAC by alias */
NULL, /* not by a binary label */
location,
locale,
NULL, /* no device attributes */
client_cred_p, /* client's credentials */
action_fcn,
NULL, /* no extra arg to pass */
&session_info ) < 0 )
{
syslog( LOG_DEBUG,
"authentication failure for '%s': %s",
user, dg_si_get_err_msg() );
exit(1);
}
/*
* Put the session in user exec mode, which sets a
* full set of credentials on the calling process.
*/
if( dg_si_set_session_mode( &session_info,
SiSModeUserExec ) < 0 )
{
syslog( LOG_ERR,
"can't set session mode for '%s': %s",
user, dg_si_get_err_msg() );
exit(1);
}
/*
* Set up the session environment.
* Just set the root directory in this example.
*/
if( session_info.root_directory != NULL )
{
if( chroot( session_info.root_directory ) < 0 )
{
syslog( LOG_INFO,
"chroot(%s) failed for '%s'",
session_info.root_directory, user );
exit(1);
}
}
/*
* Free the session information.
*/
if( dg_si_destroy_session_info( &session_info ) < 0 )
{
syslog( LOG_ERR,
"dg_si_destroy_session_info() failed for '%s': %s",
user, dg_si_get_err_msg() );
exit(1);
}
} /* end authenticate_and_set_credentials */
main()
{
authenticate_and_set_credentials();
/*
* Do whatever on behalf of the user.
*/
}
SEE ALSO
adlibrary(3), cdlibrary(3).
Licensed material--property of copyright holder(s)