Index for Section 3

Alphabetical listing for C

Bottom of page

CSSM_SetPrivilege(3)
NAME
  CSSM_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
  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_intro(3).

SEE ALSO
  Books

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

  Reference Pages

Index for Section 3

Alphabetical listing for C

Top of page