CSSM_SetPrivilege - Store privilege value in CSSM framework
# include <cdsa/cssm.h>
CSSM_RETURN CSSMAPI CSSM_SetPrivilege (CSSM_PRIVILEGE
Common Security Services Manager library (libcssm.so)
The CSSM_PRIVILEGE value to be applied to subsequent calls
to CSSM interfaces.
The CSSM_SetPrivilege() function accepts as input a privilege
value and stores it in the CSSM framework. The
integrity credentials of the module calling CSSM_SetPrivilege()
must be verified by CSSM before the privilege value
is updated. Integrity credentials are established using
CSSM_Introduce(). CSSM will perform a pointer validation
check to ensure the caller has been previously introduced.
The CSSM_SetPrivilege() function will fail if no integrity
information can be found for the caller.
After pointer validation checks, CSSM verifies the
requested privilege is authorized. This is done by comparing
Privilege with the set of privileges contained in the
caller manifest. If Privilege is not a member, the
CSSM_SetPrivilege() call fails.
Subsequent calls to the framework that require privileges
inherit the privilege value previously established by
CSSM_SetPrivilege(). CSSM will perform pointer validation
checks on the API caller before servicing the API call. If
OK, then the Privilege value is supplied to the SPI function.
Internally, CSSM builds and maintains privilege information
based on the chosen scope of the implementation. The
scope may be dictated by the capabilities of the platform
hosting the CSSM. If threading is available, the privilege
value can be associated with the thread ID of the currently
executing thread. In this scenario, CSSM can manage
a table of tuples consisting of threadID and privilege
value. If threading is not available, the privilege value
can be global to the process.
Because the selected privilege value is shared, the application
programmer should take precautions to reset the
privilege value whenever program flow leaves the caller's
module and again when control flow returns. In general,
any time there is a possibility for CSSM_SetPrivilege() to
be called while within the context of the security critical
section, CSSM_SetPrivilege() should be called again.
Otherwise, the module receiving execution control could
have called CSSM_SetPrivilege(), resulting in the privilege
value being reset.
Data structures used to maintain the global privilege
value should be initialized in CSSM_Init(). This includes
lock initialization and preliminary resource allocation.
The CSSM_Init() function is assumed to be idempotent with
respect to shared structure initialization. This means
CSSM_Init() will ensure a single thread initializes the
shared structure and subsequent calls to CSSM_Init() will
not reinitialize it. A reference count of calls to
CSSM_Init() is needed to ensure matching calls to
CSSM_Terminate() are handled.
Resource cleanup is performed at CSSM_Terminate() after
the reference count falls to zero. The last call to
CSSM_Terminate() results in shared resources being freed
and lock structures being released.
Errors are described in the CDSA technical standard. See
Intel CDSA Application Developer's Guide (see
Reference Pages [Toc] [Back]
[ Back ]