NAME

TP_CertGroupVerify

SYNOPSIS

CSSM_BOOL CSSMTPI CSSM_TP_CertGroupVerify
    (CSSM_TP_HANDLE TPHandle,
    CSSM_CL_HANDLE CLHandle,
    CSSM_CSP_HANDLE CSPHandle,
    CSSM_DL_DB_LIST_PTR DBList,
    const CSSM_CERTGROUP_PTR CertGroupToBeVerified,
    const CSSM_VERIFYCONTEXT_PTR VerifyContext);

DESCRIPTION

This function determines whether the certificate is trusted. The actions performed by this function differ based on the trust policy domain. The factors include practices, procedures and policies defined by the certificate issuer.

Typically certificate verification involves the verification of multiple 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. The supporting certificates can be contained in the provided certificate group or can be stored in the data stores specified in the DBList. This allows the trust policy module to construct a certificate group and perform verification in one operation. The data stores specified by DBList can also contain certificate revocation lists used in the verification process. It is also possible to provide a data store of anchor certificates. 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 caller can select to be notified incrementally as each certificate is verified. The CallbackWithVerifiedCert parameter (in the verifycontext) can specify a caller function to be invoked at the end of each certificate verification, returning the verified certificate for use by the caller.

Anchor certificates are a list of implicitly trusted certificates. These include root certificates, cross certified certificates, and locally defined sources of trust. These certificates form the basis to determine trust in the subject certificate.

A policy identifier can specify an additional set of conditions that must be satisfied by the subject certificate in order to meet the trust criteria. The name space for policy identifiers is defined by the application domains to which the policy applies. This is outside of CSSM. A list of policy identifiers can be specified and the stopping condition for evaluating that set of conditions.

The evaluation and verification process can produce a list of evidence. The evidence can be selected values from the certificates examined in the verification process, entire certificates from the process or other pertinent information that forms an audit trail of the verification process. This evidence is returned to the caller after all steps in the verification process have been completed.

If verification succeeds, the trust policy module may carry out the action on the specified data or may return approval for the action requiring the caller to perform the action. The caller must consult TP module documentation outside of this specification to determine all module-specific side effects of this operation.

PARAMETERS

TPHandle (input)

The handle that describes the add-in trust policy module used to perform this function.

CLHandle (input/optional)

The handle that describes the add-in certificate library module that can be used to manipulate the subject certificate and anchor certificates. If no certificate library module is specified, the TP module uses an assumed CL module, if required.

CSPHandle (input/optional)

The handle that describes the add-in cryptographic service provider module used to perform this function. If no cryptographic service provider handle is specified, the TP module allocates a suitable CSP.

DBList (input/optional)

A list of certificate databases containing certificates that may be used to construct the trust structure of both the subject and signer certificate group.

CertGroupToBeVerified (input)

A group of one or more certificates to be verified. The first certificate in the group is the primary target certificate for verification. Use of the subsequent certificates during the verification process is specific to the trust domain.

VerifyContext (input)

A structure containing policy elements useful in verifying certificates and their use with respect to a security policy. Optional elements in the verify context left unspecified will cause the internal default values to be used. Default values are specified in the TP module vendor release documents.

Some elements in the verification context are optional while others are mandatory. Usage semantics guidelines are as follows:

 

PolicyIdentifiers (input/optional)
NumberofPolicyIdentifiers (input)
AnchorCerts (input/optional)
NumberofAnchorCerts (input)
VerificationAbortOn (input/optional)
VerifyScope (input/optional)
ScopeSize (input)
Action (input/optional)
CallbackWithVerifiedCert (input/optional)
ActionData (input/optional)
Evidence (output/optional)
NumberOfEvidences (output)

RETURN VALUE

A CSSM_TRUE return value signifies that the certificate can be trusted. When CSSM_FALSE is returned, either the certificate cannot be trusted or an error has occurred. This function can also return errors specific to CSP, CL and DL modules.

ERRORS

CSSM_INVALID_TP_HANDLE

Invalid handle.

CSSM_INVALID_CL_HANDLE

Invalid handle.

CSSM_INVALID_DL_HANDLE

Invalid handle.

CSSM_INVALID_DB_HANDLE

Invalid handle.

CSSM_INVALID_CSP_HANDLE

Invalid handle.

CSSM_TP_INVALID_CERT_GROUP

Invalid certificate group structure.

CSSM_TP_NOT_SIGNER

Signer certificate is not signer of subject.

CSSM_TP_NOT_TRUSTED

Signature can't be trusted.

CSSM_TP_CERT_VERIFY_FAIL

Unable to verify certificate.

CSSM_TP_INVALID_ACTION_DATA

Invalid action data specified for action.

CSSM_TP_VERIFY_ACTION_FAIL

Unable to determine trust for action.

CSSM_TP_INVALID_ANCHOR

An anchor certificate could not be identified.

CSSM_FUNCTION_NOT_IMPLEMENTED

Function not implemented.

SEE ALSO

CSSM_CL_CertVerify, CSSM_TP_CertSign