CSSM_SetPrivilege

NAME
  CSSM_SetPrivilege - Store privilege value in CSSM framework (CDSA)

SYNOPSIS
  # include <cssm.h>

       CSSM_RETURN CSSMAPI CSSM_SetPrivilege
       (CSSM_PRIVILEGE Privilege)

LIBRARY
  Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

PARAMETERS
  Privilege (input)
          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
  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
  Errors are described in the CDSA technical standard.  See CDSA.

SEE ALSO
  Books

  Intel CDSA Application Developer's Guide (see CDSA)

  Other Help Topics