Index Index for
Section 3
Index Alphabetical
listing for C
Bottom of page Bottom of
page		 

CSSM_Init(3)


NAME

  CSSM_Init - Initialize CSSM (CDSA)


SYNOPSIS

  # include <cdsa/cssm.h>

       CSSM_RETURN CSSMAPI CSSM_Init(
       const CSSM_VERSION *Version,
       CSSM_PRIVILEGE_SCOPE Scope,
       const CSSM_GUID * CallerGuid,
       CSSM_KEY_HIERARCHY KeyHierarchy,
       CSSM_PVC_MODE *PvcPolicy,
       const void *Reserved)


LIBRARY

  Common Security Services Manager library (libcssm.so)


PARAMETERS

  Version (input)
	  The major and minor version number of the CSSM release the
	  application is compatible with.

  Scope (input)
	  The scope of the global privilege value. The scope may either
	  process scope wide (CSSM_PRIVILEGE_SCOPE_PROCESS) or thread wide
	  (CSSM_PRIVILEGE_SCOPE_THREAD).  This parameter is ignored after the
	  first call to CSSM_Init().

  CallerGuid (input)
	  The GUID associated with the caller. This GUID is used to locate
	  the caller's credentials when evaluating the request for
	  privileges.

  KeyHierarchy (input)
	  The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to
	  use when verifying integrity of the named module.

  PvcPolicy (input/output)
	  Configures the way in which pointer validation checks will be
	  performed. If not the first call to CSSM_Init(), the previously
	  configured policy is returned in the PvcPolicy bitmask and the
	  CSSM_Init() call continues processing. If successfully completed,
	  the error code CSSMERR_CSSM_PVC_ALREADY_CONFIGURED is returned.

	  _______________________________________________________________
	  Value	  Description
	  _______________________________________________________________
	  0	  PVC validation is not performed
	  1	  PVC validation is performed on application modules
	  2	  PVC validation is performed on service provider modules
	  3	  Both types of PVC validations are performed
	  _______________________________________________________________

  Reserved (input)
	  A reserved input.


DESCRIPTION

  This function initializes CSSM and verifies that the version of CSSM
  expected by the application is compatible with the version of CSSM on the
  system. This function should be called at least once by the application. It
  is an error to call any function of the CSSM API other than CSSM_Init()
  before a call to CSSM_Init() has returned successfully (that is, with
  CSSM_OK).

  Implementations of CSSM might have platform specific characteristics
  associated with the implementation of CSSM_SetPrivilege() API. The
  privilege value might have thread specific scope or process specific scope.
  The application can specify the anticipated scope at CSSM_Init(). If the
  anticipated scope is not appropriate for the implementation, an error is
  returned. The scope can be configured only once. Subsequent attempts to
  configure scope are ignored.

  CSSM integrity model includes the ability to make and check assertions
  about trusted dynamically loaded libraries. Checking assertions happens
  while the program executes. It is known as Pointer Validation Checking
  (PVC). Pointer validation checking can be applied every time execution flow
  crosses the CSSM API or SPI interfaces.

  Performing pointer validation checks has two purposes:

    ·  It allows exportation of CSSM.

    ·  It aids in detering unanticipated run-time modification of the
       program.

  The CSSM can be configured to bypass pointer validation under some
  circumstances.  Pointer validation cannot be bypassed when privileged
  operations are being performed.

  The prerequisites for performing PVC on another module, be it service
  provider, CSSM, or other library, are:

    ·  The module must have been signed and have an accompanying signed
       manifest.

    ·  The module must be loaded into process address space.

    ·  An entry-point into the module must be available.

  Typically, the entry points are discovered when a module's functions are
  called by another module. The CSSM performs pointer validation checks based
  on the configured checking policy. Checking policies are established by the
  manufacturers of CSSM and other libraries. The checking policy to be
  applied during execution is configured using the CSSM_Init() call. The
  policy can be configured once during the life of the process and occurs the
  first time CSSM_Init() is called.


PVC POLICY CONFIGURATION OPTIONS

  Pointer validation checking can be applied at the CSSM API interface, the
  CSSM SPI interface, or both. The CSSM vendor can configure a default policy
  through instructions contained in the CSSM signed manifest. Manifest
  attributes pertaining to pointer validation checking are defined as
  follows:

  Module   Tag		  Value		Description
  CSSM	   CDSA_PVC_API	  unspecified

					CSSM will
					perform PVC
					checks at the
					API boundary.
  CSSM	   CDSA_PVC_API	  OFF

					CSSM will not
					perform PVC
					checks at the
					API boundary.
  CSSM	   CDSA_PVC_SPI	  unspecified

					CSSM will
					perform PVC
					checks at the
					SPI boundary.
  CSSM	   CDSA_PVC_SPI	  OFF

					CSSM will not
					perform PVC
					checks at the
					SPI boundary.
  App	   CDSA_PVC_API	  EXEMPT

					The calling
					module is
					allowed to
					override the
					CSSM policy for
					the API
					boundary.
  App	   CDSA_PVC_API	  unspecified

					The calling
					module cannot
					weaken the CSSM
					API policy.
  App	   CDSA_PVC_SPI	  EXEMPT

					The calling
					module is
					allowed to
					override the
					CSSM policy for
					the SPI
					boundary.
  App	   CDSA_PVC_SPI	  unspecified

					The calling
					module cannot
					weaken the CSSM
					SPI policy.

  The PvcPolicy parameter to CSSM_Init() configures the run-time policy for
  the process. The PvcPolicy parameter is a bitmask allowing both API and SPI
  policies to be specified simultaneously. Unspecified policies default to
  the most conservative operational mode. CSSM performs pointer validation
  checks unless explicitly disabled.  Application modules cannot override
  CSSM policy unless exemptions are explicitly granted. The following table
  shows the what policies can be configured for various manifest attribute
  values:

  CSSM Manifest	       Calling Module Manifest

						 Acceptable PvcPolicy
						 Values

  CDSA_PVC_API=<n/a>   CDSA_PVC_API=EXEMPT

						 API checks: off (0) or
						 on (1)

  CDSA_PVC_API=OFF     CDSA_PVC_API=EXEMPT

						 API checks: off (0) or
						 on (1)
  CDSA_PVC_API=<n/a>   CDSA_PVC_API=<n/a>	 API checks: on (1)
  CDSA_PVC_API=OFF     CDSA_PVC_API=<n/a>

						 API checks: off (0) or
						 on (1)

  The following table shows the PvcPolicy configuations available for the
  SPI:

  SSM Manifest					Acceptable PvcPolicy Values

			 Calling Module
			 Manifest

			 CDSA_PVC_SPI=EXEMPT	SPI checks: off (0) or on (2)

  CDSA_PVC_SPI=<n/a>
  CDSA_PVC_SPI=OFF	 CDSA_PVC_SPI=EXEMPT	SPI checks: off (0) or on (2)
						SPI checks: on (2)

  CDSA_PVC_SPI=<n/a>

			 CDSA_PVC_SPI=<n/a>
  CDSA_PVC_SPI=OFF				SPI checks: off (0) or on (2)

			 CDSA_PVC_SPI=<n/a>

  If an application module does not have a manifest and CSSM requires the
  application module be subject to pointer validation checks, then pointer
  validation checks fail and CSSM will not operate with the anonymous module.
  All service provider modules are expected to have signed manifests.


RETURN VALUE

  A CSSM_RETURN value indicating success or specifying a particular error
  condition. The value CSSM_OK indicates success. All other values represent
  an error condition.


ERRORS

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

       CSSMERR_CSSM_SCOPE_NOT_SUPPORTED
       CSSMERR_CSSM_PVC_ALREADY_CONFIGURED
       CSSMERR_CSSM_INVALID_PVC


SEE ALSO

  Books

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

  Reference Pages

Index Index for
Section 3
Index Alphabetical
listing for C
Top of page Top of
page