Previous section.
Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group
Add-In Module Structure
An add-in module is a dynamically-linkable library, which is composed
of the following components:
-
Security Services
-
Module Administration Components
Security Services
The primary components of an add-in module are the security services
that it offers. An add-in module may provide one or more categories of
service, with each service having one or more available sub-services.
The service categories are CSP services, TP services, CL services, and
DL services. A sub-service consists of a unique set of capabilities
within a certain service. For example, in a CSP service providing
access to hardware tokens, each sub-service would represent a slot. A
TP service may have one sub-service which supports the Secure
Electronic Transfer (SET)* Merchant trust policy and a second
sub-service which supports the Secure Electronic Transfer (SET)* Cardholder
trust policy. A CL service may have different sub-services for
different encoding formats. A DL service could use sub-services to
represent different types of persistent storage. In all cases,
the sub-service implements the basic service functions for its
category of service.
A library developer may choose to implement some or all of
the functions specified in the service interface. A module developer
may also choose to extend the basic interface functionality by exposing
pass-through operations. Details of the Service Provider Interface
Functions
and their expected behavior can be found in the respective Parts
of this CDSA Technical Standard.
It may be necessary for sub-services to collaborate in order to perform
certain operations. For example, a PKCS #11 module may require
collaborating CSP and DL sub- services. Collaborating sub-services are
assumed to share state. A module indicates that two or more
sub-services collaborate by assigning them the same sub-service ID.
Sub-services may make use of other products or services as part of
their implementation. For example, an ODBC DL sub-service may make use
of a commercial database product, such as Microsoft Access*. A CL
sub-service may make use of a CA service, such as the VeriSign
DigitalID Center*, for filling certification requests. The
encapsulation of these products and
services is available to applications in the relations managed by the
Module Directory Services (MDS).
Module Administration Components
Integrity Verification
CDSA defines a dynamic environment where services are loaded on-demand.
To ensure integrity under these conditions, CSSM defines and enforces a
global integrity policy that aids in the detection of and protection
against classic forms of attack, such as stealth and man-in-the-middle
attacks. CSSM's global policy requires authentication checks and
integrity checks at module attach time.
CSSM requires successful certificate-based trust verification of all
service modules when processing a
CSSM_ModuleLoad()
request. CSSM also
requires trust verification of all Elective Module Managers when
processing a
CSSM_ModuleAttach()
request.
CSSM performs these checks during module attach. All verifications are
based on CSSM-selected public root keys as points of trust.
When CSSM performs a verification check on any component in the CSSM
environment, the verification process has three aspects:
-
Verification of identity using a certificate chain naming the
component's creator or manufacturer
-
Verification of object code integrity based on a signed hash of the
object code
-
Tightly binding the verified identity with the verified object code
CDSA defines a layered bilateral authentication procedure by which CSSM
and an add-in module can authenticate each other to achieve a mutual
trust.
An add-in module is strongly
encouraged to verify its own components.
This in-memory verification prevents stealth attacks where
the file is unaltered, but the loaded copy is tampered. CSSM always
verifies the add-in service module during attach processing. Add-in
modules are also strongly encouraged to complete bilateral
authentication with CSSM during module attach by verifying CSSM's
credentials and object code module, and verifying secure linkage with
the loaded, executing CSSM.
Module-Granted Use Exemptions
Service module vendors can choose to provide enhanced services to
selected applications or classes of applications. A module-defined use
policy is in addition to the general CSSM integrity policy. Categories
of enhanced services are defined as use exemptions. CSSM_USEE_TAG
declares the currently defined set of exemption classes. These focus
primarily on exemptions for using cryptographic services. New
exemption classes can be defined in association with any category of
security services.
Service providers should record the exemptions they grant by listing them in
an appropriate MDS relation. Currently, Cryptographic Service Providers
(CSPs) advertise their exemptions by listing them in the
UseeTag
attribute
of the MDS CSP Primary relation. This is for information only. The
verifiable authorization to grant the exemption must be recorded in the
service module's signed manifest credentials. If a module grants exemptions,
then the module's signed manifest must include a manifest attribute
attesting to this authority. The manifest attribute for currently defined
exemptions is a name-value pair with name CDSA_USEE. The associated value is
a string of base-64 encoded numbers separated by colons.
An example of CDSA_USEE tag in the manifest (which corresponds
to the base64 encoding of the CSSM_USEE_TAG) is:
-
-
CDSA_USEE: AAAAAg==:AAAABQ==:AAAAAw==
Applications can query MDS to retrieve the
UseeTags
associated with any CSP.
The numbers which are base-64 encoded are the same numbers that are defined
for CSSM_PRIVILEGE.
Exemptions which have numbers from the high order word of
the CSSM_PRIVILEGE (see
Core Services API)
use the manifest tag
CDSA_PRIV, as opposed to the tag CDSA_USEE. Other than that exception,
they are used exactly like the tags listed as CDSA_USEE*.
There are two ways for an Application to request an exemption:
-
An application can request an exemption while making a call to
the "P" functions, for example,
EncryptDataP,
DecryptDataP,
WrapKeyP
or
UnwrapKeyP,
by passing the USEE_TAG as the privilege parameter.
(If
SetPrivilege
is called and then a call is made to one of the "P" functions,
the USEE_TAG that is requested in the "P" function call will be sent
to the service provider.)
-
An application can set the privilege for all of its calls to a
service provider by calling
CSSM_Introduce()
and
CSSM_SetPrivilege()
functions. After calling
CSSM_SetPrivilege(),
CSSM will then forward the USEE_TAG that was set to the service
provider when a call is made to
EncryptData,
DecryptData,
etc.
The appropriate USEE tag that validates the requested exemption may
be in either the signed manifest of the Application (stored in the
MDS Object Directory relation), and/or in the signed manifest of the CSSM.
Either the Application or the CSSM (or both) must have a signed manifest
with the appropriate USEE tag.
A service module may also check the application manifest directly by
retrieving the application manifest from MDS and verifying the signature.
Service Module Requirements for USEE Tags Support
-
Service modules must be signed by recognized authorities who can grant
the use of the USEE tags.
-
Service modules must verify that the direct calling module is
a CSSM or CSSM or an EMM which has been introduced by a CSSM.
-
Service module may support multiple USEE privileges.
-
Service module must verify that the USEE tag supplied by the caller
matches one of the supported USEE tags.
-
Service module must list the supported USEE tags in a manifest attribute
(e.g. CDSA_USEE).
-
Use of cryptographic operations must be verified for each instance
and must fall within the restrictions implied by the USEE tag.
-
Every module of a CSP that contains cryptographic interfaces must
be included in the CSP manifest.
-
Additional components that influence the operation of the CSP should
be included in the manifest.
-
Multi-service modules that also implement CSP functionality
must enforce the rules defined here for interfaces to cryptographic functions.
-
A CSP must not allow any of its component modules' cryptographic interfaces
to be directly called by an application module.
Initialization and Cleanup
Every module must include functions for module initialization and
cleanup.
Initialization should take place when CSSM calls either
CSSM_SPI_ModuleLoad()
or
CSSM_SPI_ModuleAttach().
Cleanup is performed in
CSSM_SPI_ModuleDetach()
and
CSSM_SPI_ModuleUnload().
Click here to return to the publication details.