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:
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.
| 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. |
typedef uint32 CSSM_TP_HANDLE /* Trust Policy Handle */
typedef uint32 CSSM_TP_ACTION
typedef CSSMAPI CSSMTPI
typedef struct cssm_data {
uint32 Length;
uint8* Data;
} CSSM_DATA, *CSSM_DATA_PTR
typedef CSSM_DATA CSSM_OID, *CSSM_OID_PTR;
typedef struct cssm_field {
CSSM_OID FieldOid;
CSSM_DATA FieldValue;
}CSSM_FIELD, *CSSM_FIELD_PTR
typedef enum cssm_revoke_reason {
CSSM_REVOKE_CUSTOM,
CSSM_REVOKE_UNSPECIFIC,
CSSM_REVOKE_KEYCOMPROMISE,
CSSM_REVOKE_CACOMPROMISE,
CSSM_REVOKE_AFFILIATIONCHANGED,
CSSM_REVOKE_SUPERSEDED,
CSSM_REVOKE_CESSATIONOFOPERATION,
CSSM_REVOKE_CERTIFICATEHOLD,
CSSM_REVOKE_CERTIFICATEHOLDRELEASE,
CSSM_REVOKE_REMOVEFROMCRL
} CSSM_REVOKE_REASON
typedef enum cssm_crl_type {
CSSM_CRL_TYPE_UNKNOWN,
CSSM_CRL_TYPE_X_509v1,
CSSM_CRL_TYPE_X_509v2
} CSSM_CRL_TYPE, *CSSM_CRL_TYPE_PTR;
typedef enum cssm_crl_encoding {
CSSM_CRL_ENCODING_UNKNOWN,
CSSM_CRL_ENCODING_CUSTOM,
CSSM_CRL_ENCODING_BER,
CSSM_CRL_ENCODING_DER,
CSSM_CRL_ENCODING_BLOOM
} CSSM_CRL_ENCODING, *CSSM_CRL_ENCODING_PTR;
typedef struct cssm_dl_db_handle {
CSSM_DL_HANDLE DLHandle;
CSSM_DB_HANDLE DBHandle;
} CSSM_DL_DB_HANDLE, *CSSM_DL_DB_HANDLE_PTR;
typedef struct cssm_dl_db_list {
uint32 NumHandles;
CSSM_DL_DB_HANDLE_PTR DLDBHandle;
} CSSM_DL_DB_LIST, *CSSM_DL_DB_LIST_PTR;
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;
#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;
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;
| 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.
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;
}CSSM_TP_WRAPPEDPRODUCTINFO, *CSSM_TP_WRAPPEDPRODUCTINFO_PTR;
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;
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_DATA_PTR (CSSMTPI *CertSign) (CSSM_TP_HANDLE TPHandle,
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_DATA_PTR (CSSMTPI *CrlSign) (
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_RETURN (CSSMTPI *ApplyCrlToDb) (
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_CERTGROUP_PTR (CSSMTPI *CertGroupPrune) (
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);
} CSSM_SPI_TP_FUNCS, *CSSM_SPI_TP_FUNCS_PTR;
The manpages for Trust Policy Operations can be found at the end of this chapter.
The manpages for Extensibility Functions can be found at the end of this chapter.
| Contents | Next section | Index |