CSSM_SetPrivilege(3)CSSM_SetPrivilege(3)NAMECSSM_SetPrivilege - Store privilege value in CSSM framework (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
CSSM_RETURN CSSMAPI CSSM_SetPrivilege (CSSM_PRIVILEGE Privilege)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
The CSSM_PRIVILEGE value to be applied to subsequent calls to CSSM
interfaces.
DESCRIPTION
The CSSM_SetPrivilege() function accepts as input a privilege value and
stores it in the CSSM framework. The integrity credentials of the mod‐
ule 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_SetPrivi‐
lege() 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 mem‐
ber, 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 servic‐
ing 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 thread‐
ing is not available, the privilege value can be global to the process.
Because the selected privilege value is shared, the application pro‐
grammer 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_SetPrivi‐
lege() 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_SetPrivi‐
lege(), 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 pre‐
liminary 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 struc‐
ture 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
Errors are described in the CDSA technical standard. See
CDSA_intro(3).
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
CSSM_SetPrivilege(3)