Previous section.

Common Security: CDSA and CSSM
Copyright © 1997 The Open Group

Trust Policy Interface


A digital certificate is the binding of some identification to a public key in a particular domain. When a certificate is issued (created and signed) by the owner and authority of a domain, the binding between key and identity is validated by the digital signature on the certificate. The issuing authority also associates a level of trust with the certificate. The actions of the user, whose identity is bound to the certificate, are constrained by the trust policy governing the certificate's usage domain. A digital certificate is intended to be an unforgeable credential in cyberspace.

The use of digital certificates is the foundation on which the CDSA is designed. The CDSA assumes the concept of digital certificates in its broadest sense. Applications use the credential for:

The applications interpret and manipulate the contents of certificates to achieve these ends, based on the real-world trust model they chose as their model for trust and security. The primary purpose of a Trust Policy (TP) module is to answer the question, "Is this certificate trusted for this action?" The CSSM Trust Policy API determines the generic operations that should be defined for certificate-based trust in every application domain. The specific semantics of each operation is defined by the:

The trust model is expressed as an executable policy that is used by all applications that subscribe to that policy and the trust model it represents. As an infrastructure, CSSM is policy-neutral with respect to application-domain policies; it does not incorporate any single policy. For example, the verification procedure for a credit card certificate should be defined and implemented by the credit company issuing the certificate. Employee access to a lab housing a critical project should be defined by the company whose intellectual property is at risk. Rather than defining policies, CSSM provides the infrastructure for installing and managing policy- specific modules. This ensures complete extensibility of certificate-based trust on every platform hosting CSSM.

Policies define the credentials required for authorization to perform an action on another object. Certificates are the basic credentials representing a trust relationship among a set of two or more parties. When an organization issues certificates it defines its issuing procedure in a Certification Practice Statement (CPS). The statement identifies existing policies with which it is consistent. The statement can also be the source of new policy definitions if the action and target object domains are not covered by an existing, published policy. An application domain can recognize multiple policies. A given policy can be recognized by multiple application domains.

Evaluation of trust depends on relationships among certificates. The trust domain can define accepted sources of trust, called anchors. Anchors can be mandated by fiat or can be computed by some other means. In contrast to the sources of trust, certificate revocation lists represent sources of distrust. Trust policies may consult these lists during the verification process

Different trust policies define different actions that an application may request. Some of these actions are common to every trust policy, and are operations on objects all trust models use. The objects believed to be common to all trust models are certificates and certificate revocation records. The basic operations on these objects are sign, verify, and revoke.

Based on this analysis, CSSM defines two categories of API calls that should be implemented by TP modules. The first category allows the TP module to validate operations relevant within an application domain (such as requesting authorization to make a $200 charge on a credit card certificate, and requesting access to the locked project lab). The second category enforces operations relevant within a trust model (for example, sign, verify, and revoke) on certificates and certificate revocation lists.

Application developers and trust domain authorities benefit from the ability to define and implement policy-based modules. Application developers are freed from the burden of implementing a policy description and certifying that their implementation conforms. Instead, the application needs only to build in a list of the authorities and certificate issuers it uses.

Domain authorities also benefit from an infrastructure that supports add-in Trust Policy modules. Authorities are ensured that applications using their module(s) adhere to the policies of the domain. Also, dynamic download of trust modules (possibly from remote systems) ensures timely and accurate propagation of policy changes. Individual functions within the module may combine local and remote processing. This flexibility allows the module developer to implement policies based on the ability to communicate with a remote authority system. This also allows the policy implementation to be decomposed in any convenient distributed manner.

Implementing a Trust Policy module may or may not be tightly coupled with one or more Certificate Library modules or one or more Data Storage Library modules. The trust policy embodies the semantics of the domain. The certificate library and the data storage library embody bgcolor="#FFFFFF" the syntax of a certificate format and operations on that format. A trust policy can be completely independent of certificate format, or it may be defined to operate with one or a small number of certificate formats. A trust policy implementation may invoke a certificate library module or data storage library modules to facilitate making policy based manipulations.

The Trust Policy API defines two categories of operation:

Trust Policy Services API

CSSM defines API calls for the following types of operations:

Creating Certificates. Client applications can request that a certificate be issued to the client. It is the responsibility of the trust policy module to determine whether the client the process of requesting and obtaining the certificate. The trust policy can include is trusted to be issued a certificate. If the client is authorized, the trust policy performs provide additional authorization information to the CA and can add information, on behalf of the client, to be included in the issued certificate.

Signing Certificates and Certificate Revocation Lists. Every system should be capable of being a Certificate Authority (CA), if so authorized. CAs are applications that issue and validate certificates and certificate revocation lists (CRLs). Issuing certificates and CRLs include initializing their attributes and digitally signing the result using the private key of the issuing authority. The private key used for signing is associated with the signer's certificate. The Trust Policy module must evaluate the trustworthiness of the signer's certificate before performing this operation. Some policies may require that multiple authorities sign a newly-issued certificate. If the TP trusts the signer's certificate, then the TP module may perform the cryptographic signaturing algorithm by invoking the signing function in a Certificate library module, or by directly invoking the data signing function in a CSP module. The certificate library functions that can be used to carry out some of the TP operations are documented in the CSSM Certificate Library Interface Specification.

Verifying Certificates and Certificate Revocation Lists. The TP module determines the trustworthiness of certificates and certificate revocation lists. The test focuses on the trustworthiness of the agent who signed the document. The TP module may need to perform operations on the certificate or CRL to determine trustworthiness. If these operations depend on the data format of the certificate or CRL, the TP module uses the services of a certificate library module to perform these checks. The TP module must determine if the certificate presented is trusted to perform actions defined by the TP module. An action for a TP module might be an employee's access to a lab system housing data for a critical project. The question of whether to allow the employee to access the system is asked through this function.

Revoking Certificates. When revoking a certificate, the identity of the revoking agent is presented in the form of another certificate. The TP module must determine trustworthiness of the revoking agent's certificate to perform revocation. If the requesting agent's certificate is trustworthy, the TP module carries out the operation directly by invoking a certificate library module to add a new revocation record to a CRL, marking the certificate as revoked. The CSSM API also defines a reason parameter that is passed to the TP module. The TP may use this parameter as part of its trust evaluation.

Pass-through Function. For operations not defined in the TPI, the pass- through function allows the TP module to provide support for these services to clients. These private services are identified by operation identifiers. TP module developers must provide documentation of these services.

Trust Policy Module Operations

Interface Name Interface Description
TP_CertRequest Determines trust in issuing a certificate to the caller and initiates a certificate request to a CA.
TP_CertRetrieve Retrieves the certificate requested by TP_CertRequest.
TP_CertGroupVerify Determines whether a group of one or more certificates is trustworthy. Policy identifiers are used to specify the policy domain(s) to be evaluated by the policy module.
TP_CertSign Determines whether the signer's certificate is authorized to co-sign or notarize the target certificate. If so, The TP module carries out the operation. The scope of a signature may be used to identify which certificate field should be signed. An example is the case of multiple signatures on a certificate. Should signatures be applied to just the certificate, or to the certificate and all currently-existing signatures, as a notary public would do.
TP_CertRevoke Determines whether the revoker's certificate is trusted to perform/sign the revocation. If so, the TP module carries out the operation by adding a new revocation record to the CRL.
TP_CertGroupConstruct Construct a collection of certificates that forms a semantically related trust-relationship.
TP_CertGroupPrune Remove from a collection of certificates those that do not participate in a semantically related trust-relationship outside of the local system.
TP_CrlVerify Determines whether the CRL is trusted. This test may include verifying the correctness of the signature associated with the CRL, determining whether the CRL has been tampered with, and determining if the agent who signed the CRL is a trusted issuer of CRLs.
TP_CrlSign Determines whether the certificate is trusted to sign the CRL. If so, the TP module carries out the operation.
TP_ApplyCrlToDb Determines whether the memory-resident CRL is trusted and should be applied to a persistent database, which could result in designating certificates as revoked
TP_PassThrough Executes TP module custom operations. This function accepts as input an operation ID and an arbitrary set of input parameters. The operation ID may specify any type of operation the TP wishes to export. Such operations may include queries or services specific to the domain represented by the TP module.

Data Structures

typedef uint32 CSSM_TP_HANDLE    /* Trust Policy Handle */
typedef uint32 CSSM_TP_ACTION


The CSSM_DATA structure associates a length, in bytes, with an arbitrary block of contiguous memory. This memory must be allocated and freed using the memory management routines provided by the calling application via CSSM.
typedef struct cssm_data {
    uint32 Length;
    uint8* Data;



The length, in bytes, of the memory block pointed to by Data.


A pointer to a contiguous block of memory.


This structure stores object identifier for describing the data.


This structure contains the tag/data pair for a single field of a certificate or CRL.
typedef struct cssm_field {
    CSSM_OID FieldOid;
    CSSM_DATA FieldValue;



The object identifier which uniquely identifies this certificate or CRL field.


The data contained in this certificate or CRL field.


This structure represents the reason a certificate is being revoked.
typedef enum cssm_revoke_reason {


This structure represents the type and format used for revocation lists.
typedef enum cssm_crl_type {


This structure represents the encoding format used for revocation lists.

typedef enum cssm_crl_encoding {


This data structure holds a pair of handles, one for a data storage library and another for a data store opened and being managed by the data storage library.
typedef struct cssm_dl_db_handle {



Handle of an attached module that provides DL services.


Handle of an open data store that is currently under the management of the DL module specified by the DLHandle.


This data structure defines a list of handle pairs of (data storage library handle, data store handle).
typedef struct cssm_dl_db_list {
    uint32 NumHandles;



Number of (data storage library handle, data store handle) pairs in the list.


List of (data storage library handle, data store handle) pairs.


This structure contains a set of certificates. It is assumed that the certificates are related based on co-signaturing. The certificate group is a syntactic representation of a trust model. All certificates in the group must be of the same type.
typedef struct {
    CSSM_CERT_TYPE CertType; /* Certificate domain/type
                                                    identifier */
    CSSM_CERT_ENCODING  CertEncoding;  /* certificate encoding */
    uint32 NumCerts; /* number of elements in CertList array */
    CSSM_DATA_PTR CertList; /* List of opaque certificates */
    void *reserved;



An identifier indicating how the certificate is formatted and the domain of interpretation.


An indicator of the encoding applied to the certificates in the cert group.


Number of certificates in the group.


List of certificates.


Reserved for future use.


This structure contains certificates, CRLs and other information used as audit trail evidence.



typedef struct cssm_evidence { uint32 EvidenceForm; /* CSSM_EVIDENCE_FORM_CERT,CSSM_EVIDENCE_FORM_CRL */ union cssm_format_type { CSSM_CERT_TYPE CertType; CSSM_CRL_TYPE CrlType } FormatType ; union cssm_format_encoding { CSSM_CERT_ENCODING CertEncoding; CSSM_CRL_ENCODING CrlEncoding } FormatEncoding ; CSSM_DATA_PTR Evidence; /* Evidence content */ } CSSM_EVIDENCE, *CSSM_EVIDENCE_PTR;



An identifier directing how to interpret the evidence format.


Identifies the certificate type or the CRL type contained in the Evidence buffer.


Identifies the certificate encoding or the CRL encoding contained in the Evidence buffer.


Buffer containing audit trail components.


This data structure contains parameters useful in verifying certificate groups, certificate revocation lists and other forms of signed document
Typedef struct cssm_verify_context {
    CSSM_FIELD_PTR  PolicyIdentifiers,
    uint32 NumberofPolicyIdentifiers,
    CSSM_TP_STOP_ON VerificationAbortOn,
    CSSM_DATA_PTR AnchorCerts,
    uint32 NumberofAnchorCerts,
    CSSM_FIELD_PTR VerifyScope,
    uint32 ScopeSize,
    CSSM_TP_ACTION Action,
    CSSM_NOTIFY_CALLBACK CallbackWithVerifiedCert,
    CSSM_DATA_PTR ActionData,
    CSSM_EVIDENCE_PTR *Evidence,
    uint32 *NumberOfEvidences;



The policy identifier is a OID-value pair. The CSSM_OID structure contains the name of the policy and the value is an optional, caller-specified input value for the TP module to use when applying the policy. The name space for policy identifiers is defined externally by the application domains served by the trust policy module.


The number of Policy Identifiers provided in the PolicyIdentifiers parameter.

A pointer to the CSSM_DATA structure containing one or more Certificates to be used in order to validate the Subject Certificate. These certificates can be root certificates, cross-certified certificates, and certificates belonging to locally designated sources of trust.


The number of anchor Certificates provided in the AnchorCerts parameter.


When a TP module verifies multiple conditions or multiple policies, the TP module can allow the caller to specify when to abort the verification process. If supported by the TP module, this selection can effect the evidence returned by the TP module to the caller. The default stopping condition is to stop evaluation according to the policy defined in the TP Module. The specifiable stopping conditions and their meaning are defined as follows:

CSSM_TP_STOP_ON Definition
CSSM_STOP_ON_POLICY Stop verification whenever the policy dictates it
CSSM_STOP_ON_NONE Stop verification only after all conditions have been tested (ignoring the pass-fail status of each condition)
CSSM_STOP_ON_FIRST_PASS Stop verification on the first condition that passes
CSSM_STOP_ON_FIRST_FAIL Stop verification on the first condition that fails

The TP module may ignore the caller's specified stopping condition and revert to the default of stopping according to the policy embedded in the module.


A pointer to the CSSM_USER_AUTHENTICATION structure containing the authentication information to be used in association with this request. The authentication information may be a pass-phrase, a PIN, a completed registration form, a Certificate to facilitate a signing operation, and so on, depending on the context of the request. The required format for this credential is defined by the TP and recorded in the TPSubservice structure describing this module. If the supplied credential is insufficient, additional information can be obtained from the substructure field named MoreAuthenticationData. This field contains an immediate data value or a callback function to collect additional information from the user. If additional information is not required, this value can be NULL.


A pointer to the CSSM_FIELD array containing the OID/Value pairs that are to be used to qualify the validity of the Certificate. The context of the validity checks will be evident from each OID/Value pairing. If VerifyScope is not specified, the TP Module must assume a default scope (portions of the Subject certificate) when performing the verification process.


The number of entries in the verify scope list. If the verification scope is not specified, the input scope size must be zero.


An application-specific and application-defined action to be performed under the authority of the input certificate. If no action is specified, the TP module defines a default action and performs verification assuming that action is being requested.
It is also possible that a TP module verifies certificates for only one action.


A caller defined function to be invoked by the TP module once for each certificate examined in the verification process. The verified certificate is passed back to the caller via this function. The module invokes the callback with four input parameters. 1) module handle, 2) application specific handle, 3) reason code and 4) pointer to returned data parameter. The reason code will be CSSM_NOTIFY_CERT_VERIFIED and the data value will be a pointer to CSSM_DATA. Contained in the CSSM_DATA will be an opaque certificate. The callback function must free the CSSM_DATA structure and its contents. If the verification process completes in a single verify step, then no callbacks are made. If the callback function pointer is NULL, no callbacks are performed.


A pointer to the CSSM_DATA structure containing the action-specific data or a reference to the action-specific data upon which the requested action should be performed. If no data is specified, and the specified action requires action data then the TP module defines one or more default data objects upon which the action or default action would be performed.


A pointer to a list of CSSM_EVIDENCE objects containing an audit trail of evidence constructed by the TP module during the verification process. Typically this contains Certificates and CRLs that were used to establish the validity of the Subject Certificate, but other objects may be appropriate for other types of trust policies.


The number of entries in the Evidence list. The returned value is zero if no evidence is produced. Evidence may be produced even when verification fails. This evidence can describe why and how the operation failed to verify the subject certificate.


This structure holds information describing any backend products used by the TP module to implement its services. This descriptive information is stored in the CSSM registry when the TP module is installed with CSSM. CSSM checks the integrity of the TP module description before using the information.

The descriptive information stored in this structures can be queried using the function CSSM_GetModuleInfo() and specifying the trust policy module GUID, service mask, subservice identifier, and level of information disclosure.

typedef struct cssm_tp_wrappedproductinfo {
    CSSM_VERSION StandardVersion;
    CSSM_STRING StandardDescription;  /* Description of standard
                                        product */
    CSSM_STRING_ProductVendor;        /* Vendor of wrapped
                                        product */
    uint32   ProductFlags;



Version number of the product behind this module.


A string containing a descriptive name or title for this wrapped product.


Name of the vendor who developed (and markets) the wrapped product.


A bit mask describing attributes of the wrapped product.


Four structures are used to contain the attributes that describe a trust policy add-in module: the moduleinfo, the serviceinfo, the tp_wrappedproductinfo, and the tpsubservice structure. The first two structures are general and the attributes contained in them are applicable to all types of service modules. The last two structures are trust policy module-specific. This descriptive information is stored in the CSSM registry when the TP module is installed with CSSM. CSSM checks the integrity of the TP module description before using the information.

A trust policy module may implement multiple types of services and organize them as sub-services.

The descriptive information stored in these structures can be queried using the function CSSM_GetModuleInfo() and specifying the trust policy module GUID, service mask, subservice identifier, and level of information disclosure.

typedef struct cssm_tpsubservice {
    uint32 SubServiceId;
    char *Description;      /* Description of this subservice */
    CSSM_CERT_TYPE CertType;      /* cert types accepted by
                                                  this module */
    CSSM_CERT_ENCODING CertEncoding;   /* Encoding of cert
                                               accepted by TP */
    uint32   NumberOfPolicyIdentifiers;
    CSSM_FIELD_PTR  PolicyIdentifiers;



A unique, identifying number for the sub-service described in this structure.


A string containing a descriptive name or title for this sub-service.


A bitmask of the certificate types processed by the trust policy.


A bitmask of the certificate encodings processed by the trust policy.


An enumerated value defining the credential format accepted by the TP module. An authentication credential is required for some TP functions. Presented credentials must be of the required format.


The number of policies supported by this TP module.


A list of the policies (represented by their identifiers) supported by this TP module. There must be NumberOfPolicyIdentifiers entries in this list.


A pointer to the wrapped product description.


This data structure contains function pointers to the routines that a TP module can support. The function prototypes are provided for compiler checking when assigning function pointers to the structure. This structure is used during the registration of the TP's services. The CSSM_MODULE_FUNCS data structure defined in the CSSM Add-in Module Structure and Administration Specification uses an opaque pointer to a function table ModuleServices. When the ServiceType is CSSM_USAGE_TP the function table pointer will refer to a CSSM_SPI_TP_FUNCS data structure.
typedef struct cssm_spi_tp_funcs {
    CSSM_DATA_PTR (CSSMTPI *CertRequest)  (
        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_SUBSERVICE_UID CSPSubserviceUid,
        const CSSM_FIELD_PTR CertFields,
        uint32 NumberOfFields,
        const CSSM_FIELD_PTR  PolicyIdentifier,
        uint32 NumberOfPolicyIdentifiers,
        CSSM_CA_SERVICES MoreServiceRequests,
        const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
        sint32 *EstimatedTime,
        const CSSM_DATA_PTR ReferenceIdentifier);

    CSSM_DATA_PTR (CSSMTPI *CertRetrieve)  (
        CSSM_CL_HANDLE CLHandle,
        const CSSM_DATA_PTR ReferenceIdentifier,
        const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
        sint32 *EstimatedTime);

        CSSM_BOOL (CSSMTPI *CertGroupVerify) (CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CSP_HANDLE CSPHandle,
        CSSM_DL_DB_LIST DBList,
        const CSSM_CERTGROUP_PTR CertToBeVerified,
        const CSSM_VERIFYCONTEXT_PTR VerifyContext);

        CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DL_DB_LIST_PTR DBList,
        const CSSM_DATA_PTR CertToBeSigned,
        const CSSM_CERTGROUP_PTR SignerCertGroup,
        const CSSM_VERIFYCONTEXT_PTR SignerVerifyContext,
        const CSSM_FIELD_PTR SignScope,
        uint32 ScopeSize);

    CSSM_DATA_PTR (CSSMTPI *CertRevoke) (
        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_DL_DB_LIST_PTR DBList,
        const CSSM_DATA_PTR OldCrl,
        const CSSM_CERTGROUP_PTR CertGroupToBeRevoked,
        const CSSM_CERTGROUP_PTR RevokerCertGroup,
        const CSSM_VERIFYCONTEXT_PTR RevokerVerifyContext,
        CSSM_REVOKE_REASON Reason);

    CSSM_BOOL (CSSMTPI *CrlVerify) (
        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_DL_DB_LIST_PTR DBList,
        const CSSM_DATA_PTR CrlToBeVerified,
        CSSM_CRL_TYPE CrlType,
        CSSM_CRL_ENCODING CrlEncoding,
        const CSSM_CERTGROUP_PTR SignerCertGroup,
        const CSSM_VERIFYCONTEXT_PTR VerifyContext);

        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DL_DB_LIST_PTR DBList,
        const CSSM_DATA_PTR CrlToBeSigned,
        CSSM_CRL_TYPE CrlType,
        CSSM_CRL_ENCODING CrlEncoding,
        const CSSM_CERTGROUP_PTR SignerCertGroup,
        const CSSM_VERIFYCONTEXT_PTR SignerVerifyContext,
        const CSSM_FIELD_PTR SignScope,
        uint32 ScopeSize);

        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_DL_DB_LIST_PTR DBList,
        const CSSM_DATA_PTR CrlToBeApplied,
        CSSM_CRL_TYPE CrlType,
        CSSM_CRL_ENCODING CrlEncoding,
        const CSSM_CERTGROUP_PTR SignerCert,
        const CSSM_VERIFYCONTEXT_PTR SignerVerifyContext,

    CSSM_CERTGROUP_PTR (CSSMTPI *CertGroupConstruct) (
        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_DL_DB_LIST_PTR DBList,
        CSSM_CERTGROUP_PTR CertGroupFrag);

        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        const CSSM_DL_DB_LIST_PTR DBList,
        CSSM_CERTGROUP_PTR OrderedCertGroup);

    void * (CSSMTPI *PassThrough) (
        CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_DL_DB_LIST_PTR DBList,
        uint32 PassThroughId,
        const void *InputParams);

Trust Policy Operations

The manpages for Trust Policy Operations can be found at the end of this chapter.

Extensibility Functions

The manpages for Extensibility Functions can be found at the end of this chapter.

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