CSSM_SetPrivilege — Store privilege value in CSSM framework (CDSA)
# include <cssm.h>
CSSM_RETURN CSSMAPI CSSM_SetPrivilege
Common Security Services Manager library (cdsa$incssm300_shr.exe)
| || |
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
Errors are described in the CDSA Technical Standard.
Intel CDSA Application Developer's Guide