Previous section.

Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group

Add-In Module Structure

An add-in module is a dynamically-linkable library, which is composed of the following components:

Security Services

The primary components of an add-in module are the security services that it offers. An add-in module may provide one or more categories of service, with each service having one or more available sub-services. The service categories are CSP services, TP services, CL services, and DL services. A sub-service consists of a unique set of capabilities within a certain service. For example, in a CSP service providing access to hardware tokens, each sub-service would represent a slot. A TP service may have one sub-service which supports the Secure Electronic Transfer (SET)* Merchant trust policy and a second sub-service which supports the Secure Electronic Transfer (SET)* Cardholder trust policy. A CL service may have different sub-services for different encoding formats. A DL service could use sub-services to represent different types of persistent storage. In all cases, the sub-service implements the basic service functions for its category of service.

A library developer may choose to implement some or all of the functions specified in the service interface. A module developer may also choose to extend the basic interface functionality by exposing pass-through operations. Details of the Service Provider Interface Functions and their expected behavior can be found in the respective Parts of this CDSA Technical Standard.

It may be necessary for sub-services to collaborate in order to perform certain operations. For example, a PKCS #11 module may require collaborating CSP and DL sub- services. Collaborating sub-services are assumed to share state. A module indicates that two or more sub-services collaborate by assigning them the same sub-service ID.

Sub-services may make use of other products or services as part of their implementation. For example, an ODBC DL sub-service may make use of a commercial database product, such as Microsoft Access*. A CL sub-service may make use of a CA service, such as the VeriSign DigitalID Center*, for filling certification requests. The encapsulation of these products and services is available to applications in the relations managed by the Module Directory Services (MDS).

Module Administration Components

Integrity Verification

CDSA defines a dynamic environment where services are loaded on-demand. To ensure integrity under these conditions, CSSM defines and enforces a global integrity policy that aids in the detection of and protection against classic forms of attack, such as stealth and man-in-the-middle attacks. CSSM's global policy requires authentication checks and integrity checks at module attach time.

CSSM requires successful certificate-based trust verification of all service modules when processing a CSSM_ModuleLoad() request. CSSM also requires trust verification of all Elective Module Managers when processing a CSSM_ModuleAttach() request.

CSSM performs these checks during module attach. All verifications are based on CSSM-selected public root keys as points of trust.

When CSSM performs a verification check on any component in the CSSM environment, the verification process has three aspects:

CDSA defines a layered bilateral authentication procedure by which CSSM and an add-in module can authenticate each other to achieve a mutual trust. An add-in module is strongly encouraged to verify its own components. This in-memory verification prevents stealth attacks where the file is unaltered, but the loaded copy is tampered. CSSM always verifies the add-in service module during attach processing. Add-in modules are also strongly encouraged to complete bilateral authentication with CSSM during module attach by verifying CSSM's credentials and object code module, and verifying secure linkage with the loaded, executing CSSM.

Module-Granted Use Exemptions

Service module vendors can choose to provide enhanced services to selected applications or classes of applications. A module-defined use policy is in addition to the general CSSM integrity policy. Categories of enhanced services are defined as use exemptions. CSSM_USEE_TAG declares the currently defined set of exemption classes. These focus primarily on exemptions for using cryptographic services. New exemption classes can be defined in association with any category of security services.

Service providers should record the exemptions they grant by listing them in an appropriate MDS relation. Currently, Cryptographic Service Providers (CSPs) advertise their exemptions by listing them in the UseeTag attribute of the MDS CSP Primary relation. This is for information only. The verifiable authorization to grant the exemption must be recorded in the service module's signed manifest credentials. If a module grants exemptions, then the module's signed manifest must include a manifest attribute attesting to this authority. The manifest attribute for currently defined exemptions is a name-value pair with name CDSA_USEE. The associated value is a string of base-64 encoded numbers separated by colons. An example of CDSA_USEE tag in the manifest (which corresponds to the base64 encoding of the CSSM_USEE_TAG) is:


Applications can query MDS to retrieve the UseeTags associated with any CSP. The numbers which are base-64 encoded are the same numbers that are defined for CSSM_PRIVILEGE.

Exemptions which have numbers from the high order word of the CSSM_PRIVILEGE (see Core Services API) use the manifest tag CDSA_PRIV, as opposed to the tag CDSA_USEE. Other than that exception, they are used exactly like the tags listed as CDSA_USEE*.

There are two ways for an Application to request an exemption:

  1. An application can request an exemption while making a call to the "P" functions, for example, EncryptDataP, DecryptDataP, WrapKeyP or UnwrapKeyP, by passing the USEE_TAG as the privilege parameter. (If SetPrivilege is called and then a call is made to one of the "P" functions, the USEE_TAG that is requested in the "P" function call will be sent to the service provider.)

  2. An application can set the privilege for all of its calls to a service provider by calling CSSM_Introduce() and CSSM_SetPrivilege() functions. After calling CSSM_SetPrivilege(), CSSM will then forward the USEE_TAG that was set to the service provider when a call is made to EncryptData, DecryptData, etc.

The appropriate USEE tag that validates the requested exemption may be in either the signed manifest of the Application (stored in the MDS Object Directory relation), and/or in the signed manifest of the CSSM. Either the Application or the CSSM (or both) must have a signed manifest with the appropriate USEE tag.

A service module may also check the application manifest directly by retrieving the application manifest from MDS and verifying the signature.

Service Module Requirements for USEE Tags Support

Initialization and Cleanup

Every module must include functions for module initialization and cleanup. Initialization should take place when CSSM calls either CSSM_SPI_ModuleLoad() or CSSM_SPI_ModuleAttach(). Cleanup is performed in CSSM_SPI_ModuleDetach() and CSSM_SPI_ModuleUnload().
Click here to return to the publication details.

Contents Next section Index