%
% Copyright (c) 1999 University of Utah and the Flux Group.
% All rights reserved.
% 
% The University of Utah grants you the right to copy and reproduce this
% document or portions thereof for academic, research, evaluation, and
% personal use only, provided that (1) the title page appears prominently,
% and (2) these copyright and permission notices are retained in all copies.
% To arrange for alternate terms, contact the University of Utah at
% csl-dist@cs.utah.edu or +1-801-585-3271.
%
\label{oskit-flask}

	Flask is an operating system security architecture that
provides flexible support for security policies.  This chapter defines
the Flask-related COM interfaces that are defined by header files in
the \texttt{oskit/flask} directory.  The sections of this chapter are:
\begin{itemize}
\item[\ref{oskit-flask-types-h}] {\tt flask_types.h}:
	The basic Flask types and constants.
\item[\ref{oskit-avc}] {\tt oskit_avc}:
	The interface provided by the access vector cache (AVC) module to
	the object manager.  This interface is used by the object manager
	to perform permission checks and to register callbacks for 
	policy change notifications.
\item[\ref{oskit-avc-ss}] {\tt oskit_avc_ss}:
	The interface provided by the AVC module to the security
	server.  This interface is used by the security server
	to notify the AVC module of policy changes.
\item[\ref{oskit-security}] {\tt oskit_security}:
	The security server interface.  This interface is used by the
	AVC module to obtain access decisions, and this interface is
	used by the object manager to obtain labeling and
	polyinstantiation decisions.
\end{itemize}

	Default implementations of these interfaces are available in
{\tt liboskit_com} (the access vector cache) and {\tt
liboskit_security} (the security server).  Other code that uses these
interfaces is available in {\tt liboskit_com} (the secure file
system wrappers and the persistent SID mapping code).  A trivial
example kernel ({\tt netbsd_sfs_com}) demonstrates file permission
checks and labeling.

\apiintf{flask_types.h}{basic Flask types and constants}
\label{oskit-flask-types-h}

	This header file defines the basic types and constants
	used by the Flask-related COM interfaces.

	All objects that are controlled by the security policy are
	also labeled by the security policy with a set of security
	attributes, referred to as a \emph{security context}.  The
	\texttt{oskit_security_context_t} type is defined as a
	variable-length character string that can be interpreted by
	any application or user with an understanding of the security
	policy.  A security context might consist of several
	attributes, such as a user identity, a role, a type and a
	level, but this depends on the particular security policy.  

	As long as it is treated as an opaque string, a security
	context can be handled by an object manager without
	compromising the policy flexibility of the object manager.
	However, using security contexts for labeling and policy
	decision lookups would be inefficient and would increase the
	likelihood of policy-specific logic being introduced into the
	object managers.  Consequently, the security server defines a
	\emph{security identifier} for each active security context.
	The \texttt{oskit_security_id_t} type is defined as a 32-bit
	unsigned integer.  The null (or zero-valued) SID is always
	invalid.  A wildcard SID, \texttt{OSKIT_SECSID_WILD}, is
	defined that matches any other SID.  Certain SIDs (specified
	in \texttt{flask/initial_sids}) are predefined for system
	initialization.  The corresponding constants are defined in
	the automatically generated header file \texttt{flask/flask.h}.

	Possession or knowledge of a SID for a given security context
	does not grant any authorization for that security context.
	The SID mapping cannot be assumed to be consistent across
	executions (reboots) of the security server nor across
	security servers on different nodes.  There is no specified
	internal structure to a SID; any internal structure is known
	only by the security server. 

	When a request for a security decision is received by the
	security server, it returns the current state of the
	security policy for a set of permissions with an \emph{access
	vector}.  An access vector is a collection of related
	permissions for the pair of SIDs provided to the security
	server.  For instance, all file access permissions are grouped
	into a single access vector.  The
	\texttt{oskit_access_vector_t} type is defined as a 32-bit
	unsigned integer, with each bit representing a permission.
	The bits within an access vector are interpreted differently
	depending on the class of object.  Each object class is
	identified by an unsigned 16-bit integer value, with the
	\texttt{oskit_security_class_t} type.  The set of security
	classes is specified in \texttt{flask/security_classes}, with
	the corresponding constants in the automatically generated
	header file \texttt{flask/flask.h}.  The access vector
	interpretations are specified in \texttt{flask/access_vectors},
	and the corresponding constants are defined in the
	automatically generated header file
	\texttt{flask/av_permissions.h}.

\apiintf{oskit_avc}{AVC Interface}
\label{oskit-avc}

	The {\tt oskit_avc} interface specifies the methods provided
by the Flask AVC module to the object manager.  Primarily, these
methods are used to perform permission checks and to register
callbacks for policy changes.

	The {\tt oskit_avc} COM interface inherits from {\tt IUnknown},
and has the following additional methods:	
\begin{csymlist}
\item[compute\_av]
	Look up or create an AVC entry.
\item[audit]
	Audit permission grantings or denials.
\item[has\_perm\_ref]
	Check permissions with an AVC entry reference.
\item[has\_perm]
	Check permissions.
\item[add\_callback]
	Register a callback for a policy change event.
\item[remove\_callback]
	Remove a previously registered callback.
\item[log\_contents]
	Log the contents of the AVC.
\item[log\_stats]
	Log the AVC usage statistics.
\end{csymlist}


\api{compute_av}{Look up or create an AVC entry}
\begin{apisyn}
	\cinclude{oskit/flask/avc.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_compute_av(oskit_avc_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t requested,
			 \outparam oskit_avc_entry_ref_t *aeref);
\end{apisyn}
\begin{apidesc}
	This method is normally only called indirectly through
	\emph{oskit\_avc\_has\_perm\_ref}, but may also be called 
	directly by the object manager.
	This method looks up or creates an AVC entry that is valid for
	the {\tt requested} permissions between the SID pair ({\tt
	ssid}, {\tt tsid}), interpreting the permissions based on {\tt
	tclass}.  If no valid AVC entry exists, then this method
	calls the security server for an access decision.  Prior
	to returning, this method updates {\tt aeref} to refer 
	to the AVC entry used for this permission check.  Subsequent
	permissions checks involving the same SID pair and class
	may then use {\tt aeref} to avoid the overhead of looking up 
	the entry.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[requested]
		The permissions to be checked.
	\item[aeref]
		The reference to an AVC entry.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{audit}{Audit permission grantings or denials}
\begin{apisyn}
	\cinclude{oskit/flask/avc.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_audit(oskit_avc_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t requested,
			 oskit_bool_t denied);
\end{apisyn}
\begin{apidesc}
	This method is normally only called indirectly through
	\emph{oskit\_avc\_has\_perm\_ref}, but may also be called 
	directly by the object manager.
	This method audits a permission granting or denial,
	depending on {\tt denied}, for the {\tt requested} permissions 
	between the SID pair ({\tt ssid}, {\tt tsid}), 
	interpreting the permissions based on {\tt
	tclass}.  
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[requested]
		The permissions to be checked.
	\item[denied]
		The boolean flag indicating whether the permissions were denied.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{has_perm_ref}{Check permissions using an AVC entry reference}
\begin{apisyn}
	\cinclude{oskit/flask/avc.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_has_perm_ref(oskit_avc_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t requested,
		  	 \inoutparam oskit_avc_entry_ref_t *aeref);
\end{apisyn}
\begin{apidesc}
	This inline function determines whether the {\tt requested} permissions
	are granted between the SID pair ({\tt ssid}, {\tt tsid}),
	interpreting the permissions based on {\tt tclass}.
        If {\tt aeref} refers to a valid AVC entry for this permission
	check, then the	referenced AVC entry is used.  
	Otherwise, this	function calls the \emph{compute\_av} method to obtain
	a valid AVC entry.  If the AVC entry indicates that the permission
	check should be audited, then this inline function also invokes
	the \emph{audit} method.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[requested]
		The permissions to be checked.
	\item[aeref]
		The reference to an AVC entry.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{has_perm}{Check permissions.}
\begin{apisyn}
	\cinclude{oskit/flask/avc.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_has_perm(oskit_avc_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t requested);
\end{apisyn}
\begin{apidesc}
	This inline function is simply a wrapper for 
	\emph{oskit\_avc\_has\_perm\_ref} that does
	not require the {\tt aeref} parameter.  When
	this function is used, the \emph{compute\_av} method is
	always invoked, and the returned AVC entry reference is 
	not saved for subsequent use.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[requested]
		The permissions to be checked.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{add_callback}{Register a callback for a policy change event}
\begin{apisyn}
	\cinclude{oskit/flask/avc.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_add_callback(oskit_avc_t *avc, 
	  		 oskit_avc_callback_t *c,
			 oskit_u32_t events,
			 oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t perms);
\end{apisyn}
\begin{apidesc}
	This method registers a callback for {\tt events} with
	the SID pair ({\tt ssid}, {\tt tsid}) and the
	permissions {\tt perms}, 
	interpreting the permissions based on {\tt tclass}.  
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[c]
		The callback.
	\item[events]
		The events.
		Legal events are:
		\begin{icsymlist}
		\item[OSKIT_AVC_CALLBACK_GRANT]	Grant permissions.
		\item[OSKIT_AVC_CALLBACK_TRY_REVOKE] Revoke permissions if not retained.
		\item[OSKIT_AVC_CALLBACK_REVOKE] Revoke permissions.
		\item[OSKIT_AVC_CALLBACK_RESET]	Recheck permissions.
		\item[OSKIT_AVC_CALLBACK_AUDITALLOW_ENABLE] Enable auditing of permission grantings.
		\item[OSKIT_AVC_CALLBACK_AUDITALLOW_DISABLE] Disable auditing of permission grantings.
		\item[OSKIT_AVC_CALLBACK_AUDITDENY_ENABLE] Enable auditing of permission denials.
		\item[OSKIT_AVC_CALLBACK_AUDITDENY_DISABLE] Disable auditing of permission denials.
		\end{icsymlist}
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[perms]
		The permissions.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}

\api{remove_callback}{Remove a previously registered callback}
\begin{apisyn}
	\cinclude{oskit/flask/avc.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_remove_callback(oskit_avc_t *avc, 
	  		 oskit_avc_callback_t *c);
\end{apisyn}
\begin{apidesc}
	This method removes the specified callback.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[c]
		The callback.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}

\api{log_contents}{Log the contents of the AVC}
\begin{apisyn}
	\cinclude{oskit/flask/avc.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_log_contents(oskit_avc_t *avc, 
				int priority,
				char *tag);
\end{apisyn}
\begin{apidesc}
	This method logs the contents of the AVC.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[priority]
		The log priority.
	\item[tag]
		The log prefix tag.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{log_stats}{Log the AVC usage statistics}
\begin{apisyn}
	\cinclude{oskit/flask/avc.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_log_stats(oskit_avc_t *avc, 
				int priority,
				char *tag);
\end{apisyn}
\begin{apidesc}
	This method logs the statistics of the AVC.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[priority]
		The log priority.
	\item[tag]
		The log prefix tag.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\apiintf{oskit_avc_ss}{AVC Interface for the Security Server}
\label{oskit-avc-ss}

	The {\tt oskit_avc_ss} interface specifies the methods
provided by the Flask AVC module to the security server.  These
methods permit the security server to update the AVC state as needed
in response to policy changes.  The AVC in turn invokes any
appropriate callbacks registered by the object manager for updating
migrated permissions.

	Note that the default implementation of this interface does
not impose any controls on the use of its methods.  If controls are
desired, they must be performed by the caller of this interface.  For
example, in the Fluke implementation, where this interface is
accessible via IPC, each method is a controlled operation with a
corresponding permission check.  In contrast, in the Linux
implementation, where the security server is a component of the
monolithic kernel and the equivalent interface is only accessible
within the kernel, no controls are necessary.

	The {\tt oskit_avc_ss} COM interface inherits from {\tt IUnknown},
and has the following additional methods:	
\begin{csymlist}
\item[grant]
	Grant previously denied permissions.
\item[try\_revoke]
	Revoke previously granted permissions if those permissions are
	not retained in the state of the object manager.  Return any
	retained permissions.
\item[revoke]
	Revoke previously granted permissions.
\item[reset]
	Reset the cache to its initial state and recheck all retained
	permissions.
\item[set\_auditallow]
	Enable or disable the auditing of granted permissions.
\item[set\_auditdeny]
	Enable or disable the auditing of denied permissions.
\end{csymlist}

\api{grant}{Grant previously denied permissions}
\begin{apisyn}
	\cinclude{oskit/flask/avc_ss.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_ss_grant(oskit_avc_ss_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t perms,
			 oskit_u32_t seqno);
\end{apisyn}
\begin{apidesc}
	This method grants {\tt perms} between the SID pair 
	({\tt ssid}, {\tt tsid}), interpreting the permissions 
	based on {\tt tclass}.  Any callbacks registered by the
	object manager for the {\tt OSKIT_AVC_CALLBACK_GRANT} event are
	invoked if the other parameters match the values specified
	during registration. 
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[perms]
		The permissions.
	\item[seqno]
		The sequence number for the notification.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{try\_revoke}{Try to revoke previously granted permissions}
\begin{apisyn}
	\cinclude{oskit/flask/avc_ss.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_ss_try_revoke(oskit_avc_ss_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t perms,
			 oskit_u32_t seqno,
			 \outparam oskit_access_vector_t *out_retained);
\end{apisyn}
\begin{apidesc}
	This method tries to revoke {\tt perms} between the SID pair 
	({\tt ssid}, {\tt tsid}), interpreting the permissions 
	based on {\tt tclass}.  Any callbacks registered by the
	object manager for the {\tt OSKIT_AVC_CALLBACK_TRY_REVOKE} event are
	invoked if the other parameters match the values specified
	during registration.  These callbacks return the set of
	permissions retained in the object manager's state to the AVC.
	This method only revokes those permissions that are not
	retained in the object manager's state.
	The set of permissions that are retained in the object
	manager's state are returned in {\tt out_retained}.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[perms]
		The permissions.
	\item[seqno]
		The sequence number for the notification.
	\item[out_retained]
		The set of permissions retained.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{revoke}{Revoke previously granted permissions}
\begin{apisyn}
	\cinclude{oskit/flask/avc_ss.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_ss_revoke(oskit_avc_ss_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t perms,
			 oskit_u32_t seqno);
\end{apisyn}
\begin{apidesc}
	This method revokes {\tt perms} between the SID pair 
	({\tt ssid}, {\tt tsid}), interpreting the permissions 
	based on {\tt tclass}.  Any callbacks registered by the
	object manager for the {\tt OSKIT_AVC_CALLBACK_REVOKE} event are
	invoked if the other parameters match the values specified
	during registration.  These callbacks revoke any migrated permissions 
	prior to returning.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[perms]
		The permissions.
	\item[seqno]
		The sequence number for the notification.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{reset}{Reset the cache and recheck all retained permissions}
\begin{apisyn}
	\cinclude{oskit/flask/avc_ss.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_ss_reset(oskit_avc_ss_t *avc, 
			 oskit_u32_t seqno);
\end{apisyn}
\begin{apidesc}
	This method resets the cache to its initial state.  Any
	callbacks registered by the object manager for the {\tt
	OSKIT_AVC_CALLBACK_RESET} event are invoked.  These callbacks
	recheck all migrated permissions and revoke as necessary
	prior to returning.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[seqno]
		The sequence number for the notification.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{set\_auditallow}{Enable or disable the auditing of granted permissions}
\begin{apisyn}
	\cinclude{oskit/flask/avc_ss.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_ss_set_auditallow(oskit_avc_ss_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t perms,
			 oskit_u32_t seqno,
			 oskit_bool_t enable);
\end{apisyn}
\begin{apidesc}
	This method enables or disables the auditing of {\tt perms}
	for the SID pair ({\tt ssid}, {\tt tsid}), interpreting the
	permissions based on {\tt tclass}.  Any callbacks registered
	by the object manager for the {\tt
	OSKIT_AVC_CALLBACK_AUDITALLOW_ENABLE} or {\tt
	OSKIT_AVC_CALLBACK_AUDITALLOW_DISABLE} event are invoked.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[perms]
		The permissions.
	\item[seqno]
		The sequence number for the notification.
	\item[enable]
		The boolean flag indicating whether to enable or disable.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}



\api{set\_auditdeny}{Enable or disable the auditing of denied permissions}
\begin{apisyn}
	\cinclude{oskit/flask/avc_ss.h}

	\funcproto OSKIT_COMDECL
	oskit_avc_ss_set_auditdeny(oskit_avc_ss_t *avc, 
		         oskit_security_id_t ssid,
			 oskit_security_id_t tsid,
                         oskit_security_class_t tclass,
			 oskit_access_vector_t perms,
			 oskit_u32_t seqno,
			 oskit_bool_t enable);
\end{apisyn}
\begin{apidesc}
	This method enables or disables the auditing of {\tt perms}
	for the SID pair ({\tt ssid}, {\tt tsid}), interpreting the
	permissions based on {\tt tclass}.  Any callbacks registered
	by the object manager for the {\tt
	OSKIT_AVC_CALLBACK_AUDITDENY_ENABLE} or {\tt
	OSKIT_AVC_CALLBACK_AUDITDENY_DISABLE} event are invoked.
\end{apidesc}
\begin{apiparm}
	\item[avc]
		The access vector cache.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[perms]
		The permissions.
	\item[seqno]
		The sequence number for the notification.
	\item[enable]
		The boolean flag indicating whether to enable or disable.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\apiintf{oskit_security}{Security Server Interface}
\label{oskit-security}

	The {\tt oskit_security} interface specifies the methods provided
by the Flask security server to the object manager.  These methods
provide labeling decisions, access decisions and polyinstantiation
decisions for object managers. 

	Note that the default implementation of this interface does
not impose any controls on the use of its methods.  If controls are
desired, they must be performed by the caller of this interface.  For
example, in the Fluke implementation, where this interface is
accessible via IPC, each method is a controlled operation with a
corresponding permission check.  In the Linux implementation, the
equivalent methods are not controlled when used within the monolithic
kernel, but permission checks are performed in the system call
entrypoints that are used to provide applications with access to the
methods.

	The {\tt oskit_security} COM interface inherits from {\tt IUnknown},
and has the following additional methods:	
\begin{csymlist}
\item[compute\_av]
	Obtain an access decision.
\item[transition\_sid]
	Obtain a labeling decision.
\item[member\_sid]
	Obtain a polyinstantiation decision.
\item[sid\_to\_context]
	Obtain the security context for a given SID.
\item[context\_to\_sid]
	Obtain a SID for a given security context.
\item[register\_avc]
	Register an AVC module for policy change notifications.
\item[unregister\_avc]
	Unregister an AVC module.
\item[load\_policy]
	Load a new policy configuration.
\end{csymlist}

\api{compute_av}{Obtain an access decision}
\begin{apisyn}
	\cinclude{oskit/flask/security.h}

	\funcproto OSKIT_COMDECL
	oskit_security_compute_av(oskit_security_t *security, 
		          oskit_security_id_t ssid,
			  oskit_security_id_t tsid,
                          oskit_security_class_t tclass,
			  oskit_access_vector_t requested,
		\outparam oskit_access_vector_t *allowed,
		\outparam oskit_access_vector_t *decided,
		\outparam oskit_access_vector_t *auditallow,
		\outparam oskit_access_vector_t *auditdeny,
		\outparam oskit_u32_t *seqno);
\end{apisyn}
\begin{apidesc}
	This method is normally only called indirectly through
	the AVC module, but may also be called directly by the object manager.
	This method obtains an access decision for
	the {\tt requested} permissions between the SID pair ({\tt
	ssid}, {\tt tsid}), interpreting the permissions based on {\tt
	tclass}. 
\end{apidesc}
\begin{apiparm}
	\item[security]
		The security server.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The target object security class.
	\item[requested]
		The permissions to be checked.
	\item[allowed]
		The set of granted permissions.
	\item[decided]
		The set of decided permissions.
		Every requested permission is in this set,
		but other permission decisions may be deferred until
		explicitly requested.
	\item[auditallow]
		The set of permissions to audit when granted.
	\item[auditdeny]
		The set of permissions to audit when denied.
	\item[seqno]
		The sequence number for the granting.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{transition_sid}{Obtain a labeling decision}
\begin{apisyn}
	\cinclude{oskit/flask/security.h}

	\funcproto OSKIT_COMDECL
	oskit_security_transition_sid(oskit_security_t *security, 
		          oskit_security_id_t ssid,
			  oskit_security_id_t tsid,
                          oskit_security_class_t tclass,
			\outparam oskit_security_id_t *out_sid);
\end{apisyn}
\begin{apidesc}
	This method obtains a labeling decision for the SID pair ({\tt
	ssid}, {\tt tsid}), where the label is for an object
	with a class of {\tt tclass}. 
\end{apidesc}
\begin{apiparm}
	\item[security]
		The security server.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The security class of the object to be labeled.
	\item[out_sid]
		The SID with which to label the object.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{member_sid}{Obtain a polyinstantiation decision}
\begin{apisyn}
	\cinclude{oskit/flask/security.h}

	\funcproto OSKIT_COMDECL
	oskit_security_member_sid(oskit_security_t *security, 
		          oskit_security_id_t ssid,
			  oskit_security_id_t tsid,
                          oskit_security_class_t tclass,
			\outparam oskit_security_id_t *out_sid);
\end{apisyn}
\begin{apidesc}
	This method obtains a polyinstantiation decision for the SID
	pair ({\tt ssid}, {\tt tsid}), where the polyinstantiated object has
	a class of {\tt tclass}.
\end{apidesc}
\begin{apiparm}
	\item[security]
		The security server.
	\item[ssid]
		The source SID.
	\item[tsid]
		The target SID.
	\item[tclass]
		The security class of the polyinstantiated object.
	\item[out_sid]
		The SID of the instance to be used.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{sid_to_context}{Obtain the security context for a given SID}
\begin{apisyn}
	\cinclude{oskit/flask/security.h}

	\funcproto OSKIT_COMDECL
	oskit_security_sid_to_context(oskit_security_t *security, 
		          oskit_security_id_t sid,
			  \outparam oskit_security_context_t *scontext,
                          \outparam oskit_u32_t *scontext_len);,
\end{apisyn}
\begin{apidesc}
	This method returns the security context for the specified
	{\tt sid}.  The security context is dynamically allocated
	by the security server and must be freed by the caller.
\end{apidesc}
\begin{apiparm}
	\item[security]
		The security server.
	\item[sid]
		The SID.
	\item[scontext]
		The security context.
	\item[scontext_len]
		The length of the security context in bytes.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{context_to_sid}{Obtain the SID for a given security context}
\begin{apisyn}
	\cinclude{oskit/flask/security.h}

	\funcproto OSKIT_COMDECL
	oskit_security_context_to_sid(oskit_security_t *security, 
			  oskit_security_context_t scontext,
                          oskit_u32_t scontext_len,
			  \outparam  oskit_security_id_t *out_sid);

\end{apisyn}
\begin{apidesc}
	This method returns the SID for the specified
	{\tt scontext}.  
\end{apidesc}
\begin{apiparm}
	\item[security]
		The security server.
	\item[scontext]
		The security context.
	\item[scontext_len]
		The length of the security context in bytes.
	\item[out_sid]
		The SID.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{register_avc}{Register an AVC module for policy change notifications}
\begin{apisyn}
	\cinclude{oskit/flask/security.h}

	\funcproto OSKIT_COMDECL
	oskit_security_register_avc(oskit_security_t *security, 
			  oskit_security_class_t *classes,
			  oskit_u32_t nclasses,
			  oskit_avc_ss_t *avc);

\end{apisyn}
\begin{apidesc}
	This method registers an AVC module for policy change
	notifications.  
\end{apidesc}
\begin{apiparm}
	\item[security]
		The security server.
	\item[classes]
		The array of security classes relevant to the AVC.
	\item[nclasses]
		The number of security classes.
	\item[avc]
		The AVC module.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{unregister_avc}{Unregister an AVC module}
\begin{apisyn}
	\cinclude{oskit/flask/security.h}

	\funcproto OSKIT_COMDECL
	oskit_security_unregister_avc(oskit_security_t *security, 
	  			  oskit_avc_ss_t *avc);

\end{apisyn}
\begin{apidesc}
	This method unregisters an AVC module.
\end{apidesc}
\begin{apiparm}
	\item[security]
		The security server.
	\item[avc]
		The AVC module.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}


\api{load_policy}{Load a new policy configuration}
\begin{apisyn}
	\cinclude{oskit/flask/security.h}

	\funcproto OSKIT_COMDECL
	oskit_security_load_policy(oskit_security_t *security, 
	  			  oskit_openfile_t *openfile);

\end{apisyn}
\begin{apidesc}
	This method loads a new policy configuration from
	{\tt openfile}.  The security server invokes
	any registered AVC modules appropriately to update
	the state of the object managers for the new policy.
\end{apidesc}
\begin{apiparm}
	\item[security]
		The security server.
	\item[openfile]
		The open file.
\end{apiparm}
\begin{apiret}
	Returns 0 on success, or an error code specified in
	{\tt <oskit/error.h>}, on error.
\end{apiret}