Previous section.

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

Trust Policy Services API

Overview

The primary purpose of a Trust Policy (TP) module is to answer the question, Is this certificate authorized for this action in this trust domain? Applications are executed within a trust domain. For example, executing an installation program at the office takes place within the corporate information technology trust domain. Executing an installation program on a system at home takes place within the user's personal system trust domain. The trust policy that allows or blocks the installation action is different for the two domains. The corporate domain may require extensive credentials and accept only credentials signed by selected parties. The personal system domain may require only a credential that establishes the bearer as a known user on the local system.

The general CSSM trust model defines a set of basic trust objects that most (if not all) trust policies use to model their trust domain and the policies over that domain. These basic trust objects include:

Policies define the credentials required for authorization to perform an action on another object. (For example, a system administrator policy controls creating new user accounts on a computer system.) 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. Certificate chains represent hierarchical trust, where a root authority is the source of trust. Entities attain a level of trust based on their relationship to the root authority. Certificate graphs represent an introducer model of trust, where the number and strength of endorsers (represented by immediate links in the trust graph) increases the level of trust attained by an entity. In both models, 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.

Trust evaluation can be performed with respect to a specific action the bearer wishes to perform, or with respect to a policy, or with respect to the application domain in general. In the latter case, the action is understood to be either one specific action, or any and all actions in the domain.

When verifying trust, a Trust Policy Module (TPM) processes a group of certificates. The first certificate in the group is the target of the verification process. The other certificates in the group are used in the verification process to connect the target certificate with one or more anchors of trust. Supporting certificates can also be provided from a data store accessed by the TPM. It is also possible to provide a data store of anchor certificates. This case is less common. Typically the points of trust are few in number and are embedded in the caller or in the TPM during software manufacturing or at runtime.

The result of verification is a list of evidence, which forms an audit trail of the process. The evidence may be a list of verified attribute values that were contained in the certificates, or the entire set of verified certificates, or some other information that serves as evidence of the verification. In the end, the trust and authorizations asserted are based on the authority implied by a set of assumed or otherwise-specified public keys.

Many applications are hard-coded to select a specific trust policy. The CSSM registry and query mechanisms provide applications access to TP module descriptions. This information is provided by the TP module during installation and can assist the application in selecting the appropriate TP module for a given application domain.

Data Structures

CSSM_TP_HANDLE

This data structure represents the trust policy module handle. The handle value is a unique pairing between a trust policy module and an application that has attached that module. TP handles can be returned to an application as a result of the CSSM_ModuleAttach function. 
typedef uint32 CSSM_TP_HANDLE /* Trust Policy Handle */

CSSM_TP_ACTION

This data structure represents a descriptive value defined by the trust policy module. A trust policy can define application-specific actions for the application domains over which the trust policy applies. Given a set of credentials, the trust policy module verifies authorizations to perform these actions. 
typedef uint32 CSSM_TP_ACTION

CSSM_REVOKE_REASON

This data structure represents the reason a certificate is being revoked. 
typedef enum cssm_revoke_reason {
    CSSM_REVOKE_CUSTOM,
    CSSM_REVOKE_UNSPECIFIC,
    CSSM_REVOKE_KEYCOMPROMISE,
    CSSM_REVOKE_CACOMPROMISE,
    CSSM_REVOKE_AFFILIATIONCHANGED,
    CSSM_REVOKE_SUPERCEDED,
    CSSM_REVOKE_CESSATIONOFOPERATION,
    CSSM_REVOKE_CERTIFICATEHOLD,
    CSSM_REVOKE_CERTIFICATEHOLDRELEASE,
    CSSM_REVOKE_REMOVEFROMCRL
} CSSM_REVOKE_REASON

CSSM_TP_STOP_ON

This enumerated list defines the conditions controlling termination of the verification process by the trust policy module when a set of policies/conditions must be tested. 
typedef enum cssm_tp_stop_on {
    CSSM_TP_STOP_ON_POLICY = 0, /* use the pre-defined stopping
                                        criteria */
    CSSM_TP_STOP_ON_NONE = 1, /* evaluate all condition
                                        whether T or F */
    CSSM_TP_STOP_ON_FIRST_PASS = 2, /* stop evaluation at
                                        first TRUE */
    CSSM_TP_STOP_ON_FIRST_FAIL = 3 /* stop evaluation at
                                        first FALSE */
} CSSM_TP_STOP_ON;

CSSM_CERTGROUP

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;
} CSSM_CERTGROUP, *CSSM_CERTGROUP_PTR;
Definition

CertType

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

CertEncoding

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

NumCerts

Number of certificates in the group.

CertList

List of certificates.

reserved

Reserved for future use.

CSSM_EVIDENCE_FORM

This structure contains certificates, CRLs and other information used as audit trail evidence. 
#define CSSM_EVIDENCE_FORM_UNSPECIFIC 0x0
#define CSSM_EVIDENCE_FORM_CERT 0x1
#define CSSM_EVIDENCE_FORM_CRL 0x2


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;
Definition

EvidenceForm

An identifier directing how to interpret the evidence format.

FormatType

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

FormatEncoding

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

Evidence

Buffer containing audit trail components.

CSSM_VERIFYCONTEXT

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_USER_AUTHENTICATION_PTR UserAuthentication,
    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;
} CSSM_VERIFYCONTEXT, *CSSM_VERIFYCONTEXT_PTR;

PolicyIdentifiers

The policy identifier is an 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.

NumberofPolicyIdentifiers

The number of Policy Identifiers provided in the PolicyIdentifiers parameter.

AnchorCerts

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.

NumberofAnchorCerts

The number of anchor certificates provided in the AnchorCerts parameter.

VerificationAbortOn

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 specify-able 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.

UserAuthentication

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.

VerifyScope

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.

ScopeSize

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

Action

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.
Note:
It is also possible that a TP module verifies certificates for only one action.

CallbackWithVerifiedCert

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.

ActionData

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.

Evidence

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.

NumberOfEvidences

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.

CSSM_TP_WRAPPEDPRODUCTINFO

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; /* Descrip of standard
                                        product */
    CSSM_STRING_ProductVendor; /* Vendor of wrapped product */
    uint32 ProductFlags;
} CSSM_TP_WRAPPEDPRODUCTINFO, *CSSM_TP_WRAPPEDPRODUCTINFO_PTR;
Definition

StandardVersion

Version number of the product behind this module.

StandardDescription

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

ProductVendor

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

ProductFlags

A bit mask describing attributes of the wrapped product.

CSSM_TPSUBSERVICE

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 */
    CSSM_CALLER_AUTHENTICATION_MECHANISM AuthenticationMechanism;
    uint32 NumberOfPolicyIdentifiers;
    CSSM_FIELD_PTR PolicyIdentifiers;
    CSSM_TP_WRAPPEDPRODUCTINFO WrappedProduct;
} CSSM_TPSUBSERVICE, *CSSM_TPSUBSERVICE_PTR;
Definition

SubServiceId

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

Description

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

CertType

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

CertEncoding

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

AuthenticationMechanism

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.

NumberOfPolicyIdentifiers

The number of policies supported by this TP module.

PolicyIdentifiers

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

WrappedProduct

A pointer to the wrapped product description.

Trust Policy Operations

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

Group Functions

The manpages for Group Functions 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