NAME

CSSM_TP_CertGroupVerify

SYNOPSIS

CSSM_BOOL CSSMAPI 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 functions verifies that the subject certificate is authorized to perform an action on some data. The action and the target data are specified in the verifycontext structure along with many other input and output parameters for this operation. Anchor certificates are also specified. These are implicitly trusted certificates including root certificates, cross-certified certificates, and locally-defined sources of trust. These certificates form the basis to determine trust in the subject certificate.

The verifycontext includes a set of policy identifiers. Each policy identifier specifies an additional set of conditions that must be satisfied by the subject certificate in order to meet the trust criteria. A stopping condition for evaluating that set of conditions can also be specified.

Typically certificate verification involves the verification of multiple certificates. These certificates can be contained in the provided certificate group or supporting certificates 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. 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.

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, complete certificates from the verification 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. The location for this output is specified in the verifycontext.

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 that can be used to perform the cryptographic operations required to carry out the verification. If no CSP module is specified, the TP module uses an assumed CSP module.

DBList (input/optional)

The structure is a list of data storage library handles and data store handles. These handles should be used to store or retrieve objects (such as certificates and CRLs) related to the subject certificate and anchor certificates. If no data store is specified, the TP module uses an assumed data store module and assumed data store, if required.

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 pointer to the CSSM_VERIFYCONTEXT structure containing a set of input and output parameters. The input parameters describe how the verification process should be performed. Most of the input parameters are optional. If not specified, the TP module can use default values for unspecified inputs.

RETURN VALUE

A CSSM_TRUE return value signifies that the certificate can be trusted. It can also indicate that the action has been performed as a side effect of the operation. When CSSM_FALSE is returned, either the certificate cannot be trusted or an error has occurred. Use CSSM_GetError to obtain the error code.

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.