Previous section.

Common Security: CDSA and CSSM
Copyright © 1997 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 to four 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.

Each service category contains from ten to sixty basic service functions. 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 following specifications:

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. When an application attaches one of the collaborating sub-services, it will receive a handle which may be used to access any of the sub-services having the same sub-service ID. This mechanism may be used for collaboration across categories of services, but is not available within a single category of service.

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 exposed to applications in the CSSM_XX_WRAPPEDPRODUCT_INFO data structure, available by querying the CSSM registry.

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.

The policy requires successful certificate-based trust verification for:

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:

These steps are implemented by CSSM's Integrity Services. Integrity Services are packaged as a static library called the Embedded Integrity Services Library (EISL). EISL is available for use by the add-in module. EISL services support unilateral authentication, identity verification, object code integrity checks, and self-integrity-checks. EISL facilities are documented in the CSSM Embedded Integrity Services Library API Spec.

CDSA defines a layered bilateral authentication procedure by which CSSM and an add-in module can authenticate each other to achieve a mutual trust. EISL functions are used by the two parties to carry out the bilateral authentication procedure. An add-in module is strongly encouraged to verify its own components using the EISL self check function. 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. CSSM initiates this last portion of the bilateral authentication process by invoking the AddInAuthenticate function.

Details of the attach process, including the bilateral authentication protocol, is presented later in this section.

Module-Defined Usage Policies

Service module vendors may wish to provide enhanced services to selected applications or classes of applications. A module-defined policy is in addition to the CSSM's general integrity policy.

Module-defined policies are enforced by one of the following authentication checks:

The module specifies its policy by selecting one of these authentication checks. Options one and two use CSSM to enforce the module-defined policy during attach processing. Option three is carried out independently by the add-in module, using EISL services. The add-in module requests CSSM enforcement by setting MODULE_FLAGS corresponding to options one and two in the MODULE_INFO structure. When option two is selected, the MODULE_INFO structure should also contain a set of module-specific, public root keys corresponding to the module's points of trust.

The MODULE_INFO structure is presented to CSSM during module installation in two forms:

The policy is securely stored in the signed credentials. These credentials are authenticated by CSSM each time the module is attached. CSSM uses the signed policy description as the authoritative representation of the policy. The MODULE_INFO structure is also stored in the CSSM registry allowing applications to read the policy description by calling CSSM_GetModuleInfo.

If the CSSM_MODULE_CALLER_AUTHENTOCSSM flag is set, the module is declaring that all callers that attach this add-in module must be authenticated based on CSSM's known roots of trust. CSSM performs the authentication check on behalf of the add-in module.

If the CSSM_MODULE_CALLER_AUTHENTOMODULE flag is set, the module is declaring that all callers that attach this add-in module must be authenticated based on module-specified roots of trust. The add-in module must present the public root keys corresponding to these points of trust as input to CSSM during module installation and in the module's signed credentials.

CSSM performs the authentication check on behalf of the add-in module. The root keys specified by the add-in module are also stored in the CSSM registry, where they may be read by applications.

Add-in modules can independently authenticate applications based on module-defined points of trust. The application must incorporate a verifiable certificate in its credentials. To authenticate the application directly, the add-in module

An application's verifiable credentials must be created during application manufacturing. The application vendor must obtain a manufacturing/signing certificate from all service module vendors and CSSM vendors who will provide it with privileged status. The application vendor uses the manufacturing certificates to create the certificate chains shown in Three Module-Specific Certificate Chains . The application must carry all of these certificate chains in the signature block for its persistent, signed manifest. When the application calls CSSM_ModuleAttach on a add-in module for which it has been granted special privileges, CSSM or the service module can verify at least one of the certificate chains in the application's credentials based on CSSM-defined or module-defined roots of trust.

Figure: Three Module-Specific Certificate Chains

Initialization and Cleanup

Every module must include functions for module initialization and cleanup. The first time the module is attached, CSSM calls the module'sInitialize function to allow the module to perform any necessary initialization operations. The last time the module is detached, CSSM calls theTerminate function which allows the module to perform any necessary cleanup actions. CSSM will call the module'sEventNotify function as part of every attach and detach operation.
Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.
You should also read the legal notice explaining the terms and conditions relating to the CDSA documentation.

Contents Next section Index