NAME    [Toc]    [Back]

       CSSM_SetPrivilege  -  Store privilege value in CSSM framework
 (CDSA)

SYNOPSIS    [Toc]    [Back]

       # include <cdsa/cssm.h>

       CSSM_RETURN  CSSMAPI   CSSM_SetPrivilege   (CSSM_PRIVILEGE
       Privilege)

LIBRARY    [Toc]    [Back]

       Common Security Services Manager library (libcssm.so)

PARAMETERS    [Toc]    [Back]

       The CSSM_PRIVILEGE value to be applied to subsequent calls
       to CSSM interfaces.

DESCRIPTION    [Toc]    [Back]

       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    [Toc]    [Back]

       Errors are described in the CDSA technical standard.   See
       CDSA_intro(3).

SEE ALSO    [Toc]    [Back]

       Books

       Intel    CDSA    Application    Developer's   Guide   (see
       CDSA_intro(3))

       Reference Pages    [Toc]    [Back]




                                             CSSM_SetPrivilege(3)