Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group
Administration of Elective Module Managers
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
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:
A manifest block
A signer's information block
A signature block.
The manifest block contains:
(Optionally) Descriptive attributes of the elective module manager
A hash of each executable software component of the elective module
(Optionally) A reference to each separately link-able software
component comprising the elective module manager.
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:
A set of SHA-1 digital hashs, one per object code file
The SHA-1 hash algorithm identifier
Vendor-specified information about the elective module manager
(Optionally) A reference to each object code file that is part
of the module manager implementation.
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
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:
Generate an X.509 product certificate for the module manager and sign
it with the manufacturer's certificate.
Create an optional description of the elective module manager for
inclusion in the manifest.
Compute the SHA-1 hash for the implementation components (object code
files) used in the module manager.
Build the signature info file containing the SHA-1 hash of each
Compute a digital signature over the signature info file using
the private key of the product's certificate.
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
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:
be signed by an MDS-recognized trusted party
include the authorization attribute
[Name: CDSA_ACCESS_TAG, Value: CSSM_DB_ACCESS_WRITE]
The installation program presents its signed manifest to MDS during
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.
relation defines the following attributes to describe
elective module managers:
The module manager's globally-unique identifier (GUID)
A logical/descriptive module manager name
The vendor providing the EMM
The module manager's manifest
File system reference to locate the module manager's executable code
MDS also defines the EMM Service Provider relation, which is similar
to the MDS
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 module's globally-unique identifier (GUID)
A logical/descriptive module name
The module's service type
The module's manifest
File system reference to locate the module's executable code.
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
be signed by an MDS-recognized trusted party
include the authorization attribute
[Name: CDSA_ACCESS_TAG, Value: CSSM_DB_ACCESS_PRIVILEGED]
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
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:
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.
Once the module manager has been loaded, CSSM invokes the module
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
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.
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
CSSM invokes the module manager function
to provide the elective
module manager with a function table for accessing the CSSM services.
CSSM completes module attach processing on behalf of the EMM by
invoking the service module's interface
service module returns an SPI function table to CSSM as a result of
successful completion of this function.
CSSM invokes the elective module manager interface
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
CSSM returns a module handle and the function name to procedure
address mapping to the application that
The module manager is
responsible for verifying the CSSM that is attempting to load the
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:
CSSM performs a self integrity check.
CSSM performs an integrity check of the attaching elective module manager.
CSSM verifies secure linkage by checking that the initiation point is
within the verified object code.
CSSM invokes the elective module manager.
The elective module manager performs a self integrity check.
The elective module manager performs an integrity check of CSSM.
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
call issued by an application. The first call to
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
For every module attach of a service provider managed by an EMM, the
protocol proceeds as follows:
completion of this function, the elective module manager returns its
function table to CSSM. The function table contains module management
function pointers to
Using this function table, CSSM invokes the EMM
function. The EMM performs all service-specific initialization.
CSSM invokes the EMM
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:
A service function table supplied by the service module
A memory-management function table supplied by the application
A callback function provided by the application
CSSM invokes the
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.
CSSM invokes the EMM
interface. In response,
EMM fills in the API function addresses for the names in the
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
function are used during the life of the
attach session to support information exchange between CSSM and the
EMM. CSSM-provided services include:
Performing secure linkage checks between the application and the
Signaling CSSM of early termination of the elective module manager
(typically due to an error condition)
Providing indirect access to information and services from the
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
the same protocol for managing every module detach operation:
CSSM detaches the service module by invoking
If the detached service provider was managed by an EMM, CSSM calls
interface of the affected EMM.
Protocol for Unloading a Service Module
When an application invokes
CSSM follows the same
protocol for managing every module unload operation:
CSSM unloads the service module by invoking
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
interface of the affected EMM. The EMM should clean-up all
system state and prepare to be unloaded.
Upon return from the EMM
function, CSSM unloads the terminated EMM.
[??] Some characters or strings
that appear in the printed document are not easily
representable using HTML.
Click here to return to the publication details.