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.
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
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:
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.
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.
A GUID is defined as:
typedef struct cssm_guid {
uint32 Data1;
uint16 Data2;
uint16 Data3;
uint8 Data4[8];
} CSSM_GUID, *CSSM_GUID_PTR;
GUID generators are publicly available for Windows* 95, Windows NT*, and on many UNIX* platforms.
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.
The basic steps in bilateral authentication during module attach are defined as follows:
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.
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.
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.
| Contents | Next section | Index |