Common Security: CDSA and CSSM, Version 2 (with corrigenda)
Copyright © 2000 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
Module Administration 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:

Verification of identity using a certificate chain naming the component's creator or manufacturer
Verification of object code integrity based on a signed hash of the object code
Tightly binding the verified identity with the verified object code

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:


 

CDSA_USEE: AAAAAg==:AAAABQ==:AAAAAw==

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 CSSM Core Services) 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:

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.)
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

Service modules must be signed by recognized authorities who can grant the use of the USEE tags.
Service modules must verify that the direct calling module is a CSSM or CSSM or an EMM which has been introduced by a CSSM.
Service module may support multiple USEE privileges.
Service module must verify that the USEE tag supplied by the caller matches one of the supported USEE tags.
Service module must list the supported USEE tags in a manifest attribute (e.g. CDSA_USEE).
Use of cryptographic operations must be verified for each instance and must fall within the restrictions implied by the USEE tag.
Every module of a CSP that contains cryptographic interfaces must be included in the CSP manifest.
Additional components that influence the operation of the CSP should be included in the manifest.
Multi-service modules that also implement CSP functionality must enforce the rules defined here for interfaces to cryptographic functions.
A CSP must not allow any of its component modules' cryptographic interfaces to be directly called by an application module.

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().

Contents

Next section

Index