Functionally, CSSM provides the services shown in
Each installed component, including service modules, Elective Module Managers, and CSSM itself must insert one or more MDS records during installation. This information can be queried by applications, add-in modules, and components of CSSM. MDS protects this information base by controlling access to the information, (particularly write access), and can check the integrity of stored values upon retrieval.
MDS defines a set of relations and their associated schemas for each type of CDSA component. Using this schema information, applications can query MDS to select service modules fit to task. Searches can be performed by name or by features/capabilities. MDS schemas and facilities are fully-defined in the Module Directory Services Specification. Once an applicable module is discovered, the application uses the CSSM Load and Attach operations to load and initiate the module.
For each Attach call, CSSM creates a unique attach handle to identify the logical connection between the application and the add-in module. CSSM maintains a separate context state for each attach operation. This enables non-cooperating threads of execution to maintain their independence, even though they may share the same process space.
When dynamically loading components, CSSM ensures the integrity of the expanding system. When a module is loaded and initiated, it must present a digitally-signed credential, such as a certificate, to identify its author and publisher. The signature represents the module provider's attestation of ownership and a guarantee that the module conforms to the CSSM specification. CSSM checks the authenticity of the module's credentials and the integrity of the module's code before attaching the module to the CSSM execution environment.
Once the module has been loaded into the CSSM runtime environment, CSSM exchanges state information with the application and with the module. This allows CSSM to act as a broker between the application and a set of add-in modules. An excellent example of this brokerage service is CSSM's memory usage model. Often cryptographic operations and operations on certificates make pre-calculation of memory block sizes difficult and inefficient. CSSM rectifies this problem through registration of application memory allocation callback functions. CSSM and attached add-in modules use the application's memory functions to create complex or opaque objects in the application's memory space. Memory blocks allocated by an add-in module and returned to the application can be freed by the application using its chosen free routine.
When an application no longer requires a module's services, the add-in module can be detached. An application should not invoke this operation unless all requests to the target module have been completed. Modules can also be uninstalled. The uninstall process must delete the MDS records associated with the module.
The dynamic nature of the elective module manager is transparent to the add-in module also. This is important. It means that an add-in module vendor should not need to modify their module implementation to work with an elective module manager, versus a basic module manager.
There is at most one module manager for each category of service loaded in CSSM at any given time. When an elective module manager is dynamically added to service an application, that module is a peer of all other module managers and can cooperate with other managers as appropriate.
When an attached application detaches from an add-in service module, CSSM will also unload the associated module manager if it is not in use by another application.
This information can be queried, but typically only system administration applications will use MDS-managed information about module managers. For example, a smart installer for an add-in module may check to see that the corresponding module manager is also installed on the local system. If not, then the installer can also install the required module manager. This does not affect the implementation of the add-in module itself, just the install program for that module.
The other module managers must be able to:
When module managers share state information they must implement conditional logic to interact with each other. Different mechanisms can be used to share state information:
The first two mechanisms depend on platform services outside of CDSA. Module managers that share state information can use all of these mechanisms. However, using custom internal interfaces or OS-specific mechanisms is discouraged as it detracts from creating portable EMMs. When using CSSM-supported messaging, module managers should define and publish a message-based protocol, so that all implementations of the participating module managers could choose to support the message protocol.
CSSM-supported event notification requires that all module managers implement and register with CSSM an event notification entry point. Module managers issue notifications by invoking a CSSM function, specifying:
CSSM delivers the notification to the destination module manager by invoking the manager's notification entry point.
Generic message types include:
These service categories are considered basic because we believe that all applications using security services must use these services. Cryptographic services are the heart of security services and protocols. Identity, authentication, and integrity are embodied in digital credentials (such as certificates). A user's certificates must be persistently stored for use as long-term credentials. Policies will exist for how and when the credentials can be used. A security-aware application that does not use these services is unusual.
CSSM maintains these module managers in the system at all times and exports their respective APIs to all applications. Elective module managers export their APIs to applications on demand. When active in the CSSM environment, all module managers are peers, all are managed uniformly by CSSM, and all may cooperate and coordinate with each other as required to perform their tasks.
Calls to the CSSM security API can originate in an
application, in another add-in security
module, or in CSSM itself.
CSSM ensures access to CSSM internal structures is serialized through thread synchronization primitives. If CSSM is implemented as a shared library then process synchronization primitives are also employed. Add-in modules need not have multi-threaded implementations to interoperate with CSSM. Multi-threaded capabilities are registered with CSSM at module install time. Access to non-multithreaded add-ins is serialized by CSSM.
Modules must be loaded before they can receive function calls from a dispatcher. An error condition occurs if the invoked function is not implemented by the selected module.
Both parties in the bilateral procedure must have three pieces of signed credentials:
These credentials are stored in s Module Directory Services relation that records information about CDSA components. CSSM's credentials are also stored in MDS during CSSM installation.
During ModuleLoad and ModuleAttach processing, CSSM performs the first half of the bilateral protocol, which proceeds as follows:
The component completes the authentication procedure as follows:
When the three credentials verify, it is still necessary to ensure secure linkage between the components. For the CSSM, this entails checking that the called address is in fact in the appropriate code module. For the attaching component, the return address must be verified to be within the CSSM calling module. (Even in the case of self-checking, one may require that the return address be within the module being checked.)
Linkage checks prevent attacks of the stealth class, where the object being verified is not the object that is being used. Also, the checks increase the difficulty of the man-in-the-middle attack, where a rogue component will insert itself between two communicating modules, masquerading itself as the other component to each component.
Secure linkage checks can be performed each time CSSM invokes a service module. Service modules are encouraged to perform a secure linkage check on CSSM before servicing a call, particularly if the requested operation is a privileged service.
Bilateral authentication should also be performed between applications and CSSM. This requires a manufacturing, installation and start-up process in which applications can:
The enhanced, off-line manufacturing process for all dynamic components of CDSA is as follows:
When manufactured in this manner, the identity and integrity of the component can be checked. Applications that wish to present credentials for privileged services or to be authenticated by CSSM must follow an analogous manufacturing process.
CSSM can provide verification services without assuming any central authority as the universal base of trust. Software vendors can cross-license with other vendors using their digital signature. These root keys can be provided to CSSM integrity services. CSSM can perform authentication based on these additional roots of trust only if the keys are signed and that signature can be verified by CSSM based on previously known roots of trust.
The field upgrade procedures necessary to support cross-certification in deployed systems may not be practical. For this reason, a single, industry-wide root of trust for integrity verification is strongly encouraged. Additional signatures representing private business agreements could be required and verified in those situations where deemed necessary.
The verification tests can be applied as a self-check or to check another component in the CSSM environment. Periodic, runtime re-checks can be performed to verify constancy of a component's integrity. If tampering is detected in any component, the verification function will interrupt system execution or return a denial of service error to the caller.
Verification services are available for use on demand by add-in modules, module managers, applications, and CSSM itself.
Once cryptographic contexts have been created the application may freely use those contexts without CSSM-imposed security checks. Security contexts may contain secrets, such as encryption keys, and other credentials. Applications are responsible for protecting these secrets. Applications desiring maximal protection should use passphrase callback functions that limit the duration in which the passphrase or other credentials are visible in the system.
Applications retain handles to each security context used during execution. The context handle is a required input parameter to many security service functions. Most applications instantiate and use multiple security contexts. Only one context may be passed to a function, but the application is free to switch among contexts at will, or as required (even per function call).
A knowledgeable CSP-aware application initializes the security context structure with values obtained by querying the Module Directory Services to obtain the capabilities of a Cryptographic Service Provider (CSP).
The context creator owns the cryptographic context. Because the context can contain secrets, the context can be used by other agents only if the context creator has authorized that agent to use the context on their behalf.
An application may create multiple contexts directly or
indirectly. Indirect creation may occur when invoking
layered services, system utilities, trust policy modules,
certificate library modules, or data storage library
modules, that create and use their own appropriate security
context as part of the service they provide to the invoking
These hidden contexts do not concern the application developer, as they are managed entirely by the layered service or add-in module that creates them. Each process or thread that creates a security context is responsible for explicitly terminating that context.
Security context management provides mechanisms that: