Previous section.

Common Security: CDSA and CSSM
Copyright © 1997 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's verification mechanism is provided by the Embedded Integrity Services Library (EISL). This library defines basic integrity services and packaged services that implement standard integrity protocols. CSSM extends these services by defining additional 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. To verify its own components, the module manager should use the Embedded Integrity Services Library's self check function. This in-memory verification prevents stealth attacks where the disk-resident object file is unaltered, but the loaded code is tampered. Additional functions are provided by the EISL for verifying 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 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. A full set of credentials includes:

These three files must be zipped to form a single set of credentials. Multiple implementations of standard zip algorithms interoperate on one or more platforms, hence a zipped, signed manifest retains a substantial degree of interoperability.

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 CSSM Embedded Integrity Services Library 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, no 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 and manipulation of manifests and certificate credentials is specified in the CSSM Embedded Integrity Services Library API Spec and the CDSA Signed Manifest Specification, which are included in the CDSA document set.

Installing an Elective Module Manager

Although the dynamic nature of an elective module manager is transparent to application, the elective module manager must be installed with CSSM before an application can use an add-in module of the service category defined and managed by the elective module manager. The name given to an elective module manager includes both a logical name and a globally-unique identifier (GUID). The logical name is a string chosen by the module manager developer to describe the module. The GUID is a structure used to differentiate among all components (for example, elective module managers and add-in modules) recorded in the CSSM registry. GUIDs are discussed in more detail below. The location of the module manager implementation is required at installation time so CSSM can locate the module manager and its credentials when the module manager must be loading into the system.

The module manager must also define and register a service mask with CSSM. This mask names the new category of security services defined by the elective module manager. CSSM defines a service mask for each of the four basic security service categories. The remainder of the name space for service masks is managed outside of CDSA. Module manager vendors are responsible for selecting a unique service mask for their new category of security service.

Add-in modules that implement a new category of security service and applications that use the new category of service use the service mask defined by the manager's vendor to identify the selected class of service. A single instance of an elective module manager can be registered with CSSM. Versions are not permitted. Applications and add-in modules have compile-time knowledge of the service mask value that identifies the module manager's category of service. CSSM core learns of new service masks during the installation of an elective module manager.

Global Unique Identifiers (GUIDs)

Each module manager must have a globally-unique identifier (GUID) that CSSM and the module manager itself uses to uniquely identify the manager for install and de-install operations. A module manager can also use its GUID to identify itself when it sets an error.

A GUID is defined as:

typedef struct cssm_guid {
    uint32 Data1;
    uint16 Data2;
    uint16 Data3;
    uint8 Data4[8];

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_ModuleAttach function 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 CSSM registry 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 initiates a call to an OS-specific main entry point in the module manager. Within the main function, the elective module manager must perform integrity self-check using EISL. Upon return, CSSM invokes the ModuleManagerAuthenticate function. The elective module manager must implement this function. The function must verify CSSM and its credentials completing the second half of the CSSM bilateral authentication protocol.

  3. Upon successful completion of the bilateral authentication protocol, the elective module manager registers a small table of function pointers for CSSM to module manager communications.

  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.

The Embedded Integrity Services Library (EISL) must be used to perform 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. When EISL returns a failure condition, then either the CSSM has been tampered 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 register it interface function table with the suspect CSSM. The module manager should perform clean-up operations and exit voluntarily. The module manger has refused to provide service in an environment that it could not verify. If verification succeeds, then the module manager should proceed to register with CSSM.

Elective Module Manager Entry Point

When CSSM loads a module manager, it initiates an OS-specific entry point. For the Windows NT* operating system, DLLMain is the entry point. For SunOS, _init and _fini are the entry points. Upon load, this function will be responsible for performing self-check and returning to CSSM. The module manager function ModuleManagerAuthenticate is responsible for authenticating CSSM and then calling CSSM_RegisterManagerServices to register a function table with CSSM. Upon unload, the corresponding OS-specific entry point is invoked. This function is responsible for calling CSSM_DeregisterManagerServices. To avoid OS-related conflicts, any setup or cleanup operations should be performed in the module's Initialize and Terminate functions.

Bilateral Authentication

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 CSSM bilateral authentication protocol is supported by the services of the CSSM Embedded Integrity Services Library (EISL).

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.

The EISL is an embedded subset of the Integrity Services Library (ISL). Each authenticating entity invokes EISL functions to carry out the steps in this process. The following EISL functions are used to carry out the seven step bilateral authentication protocol:

The EISL Verify functions check all aspects of a module manager's credentials, including the certificate chain, the signature on the manifest, the signature on the product description, and the signature on each object code file. The EISL Verify functions cannot check for secure linkage. CSSM and the elective module manager must use the EISL 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. To free the data structures used in bilateral authentication, EISL provides a Recycle function.

Module Manager Function Table Registration

Upon load, a module manager must register its function tables with CSSM by calling CSSM_RegisterServices. Its function table contains module management function pointers to Initialize, Terminate, RegisterDispatchTable, DeregisterDispatchTable, and EventNotifyManager.

CSSM invokes the initialize function providing its major and minor version numbers as input. The elective module manager must determine compatibility with the specified CSSM version and performs any additional, required initialization operations.

When an application attaches an add-in service module of the category managed by the elective module manager, CSSM invokes the RegisterDispatchTable function. The functions passes to the module manager:

The module handle uniquely identifies the session between the application and the add-in module instance.

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.

The functions are provided as a set of memory management upcalls. The functions are the application's equivalent of malloc, free, calloc, and re-alloc. 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.

The service function table is the function table of an add-in service module. The table entries correspond to the Service Provider Interfaces (SPIs) defined by the elective module manager for the new category of security service. The elective module manager uses the function table to dispatch application calls for service to attached add-in modules. Multiple applications and multiple instances of an add-in module can be concurrently active. The single elective module manager is responsible for managing all of these concurrent sessions.

CSSM invokes the DeregisterDispatchTable to inform the elective module manager of the termination of a particular application and add-in module session. The module handle is used to identify the terminating session.

CSSM invokes the terminate function to inform the elective module manager that all of the application and add-in module sessions of the service types managed by that elective module manager have terminated and the CSSM is going to unload the elective module manager. The elective module manager must perform any cleanup tasks and make all preparations for unloading.

Error Handling

When an error occurs inside a module manager, the manager should call CSSM_SetError. The CSSM_SetError function takes the manager's GUID and an error number as inputs. The manager's GUID is used to identify where the error occurred. The error number will be used to describe the error.

The error number set by a module manager should fall into one of two ranges. The first range of error numbers is pre-defined by CSSM. These are errors that are common to all module managers in CSSM. The second range of error numbers is used to define error codes specific to the service category. These category-specific error codes must be in the range of CSSM_XX_PRIVATE_ERROR to CSSM_XX_END_ERROR, where XX stands for the service category abbreviation (such as, CSP, TP, CL, DL), defined by the elective module manager. Each service developer is responsible for making the definition and interpretation of their category-specific error codes available to applications.

When no error has occurred, but the appropriate return value from a function is CSSM_FALSE, that function should call CSSM_ClearError before returning. When the application receives a CSSM_FALSE return value, it is responsible for checking whether an error has occurred by calling CSSM_GetError. If the module function has called CSSM_ClearError, the calling application receives a CSSM_OK response from the CSSM_GetError function, indicating no error has occurred.

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