Previous section.

Common Security: CDSA and CSSM, Version 2 (with corrigenda)
Copyright © 2000 The Open Group

Administration of Elective Module Managers

Integrity Verification

CSSM provides a set of integrity services that can be used by elective module managers to verify the integrity of themselves and of other components in the CSSM environment. CSSM requires the use of a strong verification mechanism to screen all components as they are dynamically added to the CSSM environment. This aids in CSSM's detection and protection against the classic forms of attack:

CSSM defines layered protocols, such as bilateral authentication, to perform identity, integrity, and authorization checks during dynamic binding.

CSSM verifies elective module managers prior to loading them. Verification prior to loading prevents activating file viruses in infected modules. Once verified, CSSM can use the module manager's signed manifest to perform address validity checks, insuring secure linkage to the module manager.

A module manager is required to verify the integrity of its own subcomponents and of CSSM as part of the transparent attach process. This in-memory verification prevents stealth attacks where the disk-resident object file is unaltered, but the loaded code is tampered. Additionally, a module manager should verify the integrity of and secure linkage with CSSM. CSSM initiates this part of the verification process by invoking the ModuleManagerAuthenticate() function implemented by the elective module manager.

Module Manager Credentials

Integrity verification is based on the module manager's signed manifest credentials. A complete set of credentials must be created for each CSSM elective module manger as part of the software manufacturing process. These credentials are required by CSSM in order to maintain the integrity of the CDSA system. Signed manifest credentials consist of three sub-blocks:

The manifest block contains:

These three sub-blocks form a single set of credentials. The credentials are stored as an attribute of the module manager. All module manager attributes are stored in relations managed by MDS. The module manager's manifest is stored as a binary blob representation of the manifest file in the MDS EMM relation.

The module manager's certificate is the leaf in a certificate chain. The chain is rooted at one of a small number of known, trusted, cross-certified certificates. A simple case is shown in Certificate Chain for an Elective Module Manager. A CSSM vendor issues a certificate to the elective module manager vendor, signed with the private key of the CSSM vendor's certificate. The elective module manager vendor issues a certificate for each of its products, signing the product certificate with its own certificate. The elective module manager embeds a set of CSSM vendor public root keys. These key are recognized points of trust and are used when verifying a module manager's certificate. By incorporating multiple certificate chains in the signature file an elective module manager can be verified by multiple CSSM installations, not just those created by one specific root vendor.


Figure: Certificate Chain for an Elective Module Manager

The manifest associated with an elective module manager describes the module manager component. A manifest file includes:

The object code files are standard OS-managed entities. Object files do not embed their digital signatures, instead, signatures are stored in a manifest separate from, but related to, the object files.

A digest of each manifest section is then computed and stored in the signature info file.

The signature file contains the last PKCS#7 signature computed over all of the related manifest entries, including the signatures contained in the manifest.

This set of credentials must be manufactured when the module manager is manufactured. Assuming the elective module manager vendor already has a certificate from a CSSM manufacturer, the manufacturing process for an elective module manager proceeds as follows:

  1. Generate an X.509 product certificate for the module manager and sign it with the manufacturer's certificate.

  2. Create an optional description of the elective module manager for inclusion in the manifest.

  3. Compute the SHA-1 hash for the implementation components (object code files) used in the module manager.

  4. Build the signature info file containing the SHA-1 hash of each manifest section.

  5. Compute a digital signature over the signature info file using the private key of the product's certificate.

  6. Create the PKCS#7 signature file containing the signature info file digest, the signature over the signature info file, and all of the elective module manager certificates.

It is of the utmost importance that the object code files and the manifest be signed using the private key associated with the product certificate. This tightly binds the identity in the certificate with "what the elective module manager is" (that is, the object code files themselves) and the vendor identified in the certificate.

The structure of manifests and certificate credentials is specified in the CDSA Signed Manifests specification Part of this document.

Installing an Elective Module Manager

Before an application can use an elective service through CSSM, the elective module manager and at least one elective service module must be installed on the local system and registered with CDSA. The installation program must use platform-specific services to install the module manager on the local system. The installation program must use Module Directory Services (MDS) to register the EMM with CDSA. The installation program must create at least one record in the MDS EMM relation. To insert new records, the installation program must have write-access to the MDS CDSA Directory database. MDS controls write-access to all MDS databases. Write-access is granted only to signed, authorized applications. The installation program must be a signed application presenting a signed manifest credential. The program's credential must:

The installation program presents its signed manifest to MDS during DbOpen. If MDS successfully verifies the installation program's signed manifest credential, then write-access is granted and the program can proceed to insert new records into the MDS CDSA Directory database.

The MDS EMM relation defines the following attributes to describe elective module managers:

MDS also defines the EMM Service Provider relation, which is similar to the MDS Common relation. The EMM Service Provider relation stores the general attributes applicable to all elective service modules that are managed by some elective module manager registered with CDSA. Attributes in the EMM Service Provider relation include:

The EMM service provider attributes are very general. The vendor providing the Elective Module Manager may wish to add new relations to the MDS CDSA Directory database to store more detailed descriptions of the services and capabilities of the service modules providing the new service. These new relations should be created during module manager installation. The schema for these relations is defined by the vendor of the new elective service category.

To create new relations, the installation program must have schema-modification-rights to the MDS CDSA Directory database. MDS controls schema-modification-rights to all MDS databases. Schema-modification-rights are granted only to signed, authorized applications. The installation program must be a signed application presenting a signed manifest credential. The program's credential must:

Global Unique Identifiers (GUIDs)

Each module manager must have a globally-unique identifier (GUID) that CSSM and the module manager itself use to uniquely identify the manager for integrity verification operations.

GUID generators are publicly available for Windows[??] 95, Windows NT[??], and on many UNIX[??] platforms.

Loading an Elective Module Manager

Before an application can use the functions of a specific add-in module, it must use the CSSM_ModuleLoad() and CSSM_ModuleAttach() functions to request that CSSM attach to the module. If the add-in module implements an elective category of service and its module manager is not currently loaded, CSSM searches the Module Directory Services EMM relation for an appropriate module manager and loads it using the following process:

  1. CSSM verifies the integrity of the elective module manager code prior to loading the object code module, performing the first half of the CSSM bilateral authentication protocol.

  2. Once the module manager has been loaded, CSSM invokes the module manager interface ModuleManagerAuthenticate(). This function should perform integrity self-check using EISL services. The function should also verify CSSM based on its signed manifest credentials. This completes the second half of the CSSM bilateral authentication protocol.

  3. Upon successful completion of the bilateral authentication protocol, the elective module manager returns a small table of function pointers that CSSM uses to invoke the elective module manager.

  4. Using the function table provided by the elective module manager, CSSM invokes the module manager's Initialize function, allowing the module manager to complete additional initialization processing, if required.

  5. CSSM invokes the module manager function RegisterDispatchTable() to provide the elective module manager with a function table for accessing the CSSM services.

  6. CSSM completes module attach processing on behalf of the EMM by invoking the service module's interface CSSM_SPI_ModuleAttach(). The service module returns an SPI function table to CSSM as a result of successful completion of this function.

  7. CSSM invokes the elective module manager interface RefreshFunctionTable(), requesting that the EMM initialize the function name to procedure address mapping for return to the calling application. These function addresses should correspond to procedures within the EMM. These procedures implement the mapping of APIs to SPIs.

  8. CSSM returns a module handle and the function name to procedure address mapping to the application that invoked the CSSM_ModuleAttach() operation.

Bilateral Authentication

The module manager is responsible for verifying the CSSM that is attempting to load the module manager. If verification fails, the module manager is responsible for terminating the attach process. If verification fails, then either the CSSM has been tampered with or the attaching module manager does not recognize the CSSM's certificate. The module manager must terminate the attach process. The module manager should not return the interface function table to the suspect CSSM. The module manager should perform clean-up operations and exit voluntarily. The module manager has refused to provide service in an environment that it could not verify.

Upon load, CSSM and the elective module manager verify their own and each other's credentials by following CSSM's bilateral authentication protocol. The practice of self-checking and cross-checking by other parties increases the level of tamper detection provided by CDSA.

The basic steps in bilateral authentication during module attach are defined as follows:

  1. CSSM performs a self integrity check.

  2. CSSM performs an integrity check of the attaching elective module manager.

  3. CSSM verifies secure linkage by checking that the initiation point is within the verified object code.

  4. CSSM invokes the elective module manager.

  5. The elective module manager performs a self integrity check.

  6. The elective module manager performs an integrity check of CSSM.

  7. The elective module manager verifies secure linkage by checking that the function call originated from the verified CSSM.

CSSM and the elective module manager must use address checking functions to verify secure linkage with the party being verified. The purpose of the secure linkage check is to verify that the object code just verified is either the code you are about to invoke or the code that invoked you.

Protocol for Attaching a Service Module

CSSM and an EMM perform the same protocol for each CSSM_ModuleAttach() call issued by an application. The first call to CSSM_ModuleAttach() causes the EMM to be verified and loaded. Subsequent calls do not repeat the verification and load process, but all other steps are the same for every application call to CSSM_ModuleAttach().

For every module attach of a service provider managed by an EMM, the protocol proceeds as follows:

  1. CSSM invokes ModuleManagerAuthenticate(). Upon successful completion of this function, the elective module manager returns its function table to CSSM. The function table contains module management function pointers to Initialize, Terminate, RegisterDispatchTable, DeregisterDispatchTable, and EventNotifyManager.

  2. Using this function table, CSSM invokes the EMM Initialize() function. The EMM performs all service-specific initialization.

  3. CSSM invokes the EMM RegisterDispatchTable() function. This function provides the EMM with a set of CSSM service functions that the module manager can use to obtain information about the attaching service module and the application that loaded and attached the module. Information accessible through these functions includes:

  4. CSSM invokes the CSSM_SPI_ModuleAttach() interface of the service module to complete attach-processing on behalf of the EMM. The service module can perform verification of the CSSM and the calling application (particularly to verify the application's request for any use exemptions). The primary result returned from the service provider to CSSM is the SPI function table containing the entry points for the service operations implemented by the service module.

  5. CSSM invokes the EMM RefreshFunctionTable() interface. In response, EMM fills in the API function addresses for the names in the FuncNameAddr table.

  6. CSSM returns the name-to-address mapping table for the APIs to the calling application, completing the module attach operation.

The CSSM service functions provided to the elective module manager via the RegisterDispatchTable() function are used during the life of the attach session to support information exchange between CSSM and the EMM. CSSM-provided services include:

The application services available through CSSM include use of the application's memory management functions and access to an application's callback function.

All memory allocation and de-allocation for data passed between the application and any part of CSSM is ultimately the responsibility of the calling application. If the elective module manager provides direct services to an application in addition to those services provided by the add-in modules it manages, and the module manager needs to allocate memory to return data to the application, the application-provided memory management functions must be obtained through CSSM and used by the elective module manager.

The functions are provided as a set of memory management upcalls. The functions are the application's equivalent of malloc, free, calloc, and realloc. The supplied functions are expected to have the same behavior as those functions. The function parameters will consist of the normal parameters for that function. The function return values should be interpreted in the standard manner. A module manager is responsible for making the memory management functions available to all of its internal functions that require it.

Protocol for Detaching a Service Module

When an application invokes CSSM_ModuleDetach(), CSSM follows the same protocol for managing every module detach operation:

  1. CSSM detaches the service module by invoking ModuleDetach().

  2. If the detached service provider was managed by an EMM, CSSM calls the DeregisterDispatchTable() interface of the affected EMM.

Protocol for Unloading a Service Module

When an application invokes CSSM_ModuleUnload(), CSSM follows the same protocol for managing every module unload operation:

  1. CSSM unloads the service module by invoking CSSM_ModuleUnload().

  2. If the detached service provider was managed by an EMM, CSSM decrements a load-counter. If the load-counter is zero, then CSSM calls the Terminate interface of the affected EMM. The EMM should clean-up all system state and prepare to be unloaded.

  3. Upon return from the EMM Terminate function, CSSM unloads the terminated EMM.

[??] Some characters or strings that appear in the printed document are not easily representable using HTML.

Contents Next section Index