This function verifies the signatures on each certificate in the group. Each certificate in the group has an associated signing certificate that was used to sign the subject certificate. Determination of the associated signing certificate is implied by the certificate model. For example, when verifying an X.509 certificate chain, the signing certificate for a certificate C is known to be the certificate of the issuers of certificate C. In a multisignature, web of trust model, the signing certificates can be any certificates in the CertGroup or unknown certificates.

Signature verification is performed on the VerifyScope fields for all certificates in the CertGroup. Additional validation tests can be performed on the certificates in the group depending on the certificate model supported by the TP. For example, certificate expiration dates can be checked and appropriate CRLs can be searched as part of the verification process.

CSSM_BOOL CSSMAPI CSSM_TP_CertGroupVerify
                        (CSSM_TP_HANDLE TPHandle,
                        CSSM_CL_HANDLE CLHandle,
                        CSSM_DL_DB_LIST_PTR DBList,
                        CSSM_CSP_HANDLE CSPHandle,
                        const CSSM_FIELD_PTR PolicyIdentifiers,
                        uint32 NumberofPolicyIdentifiers,
                        CSSM_TP_STOP_ON VerificationAbortOn,
                        const CSSM_CERTGROUP_PTR CertToBeVerified,
                        const CSSM_DATA_PTR AnchorCerts,
                        uint32 NumberofAnchorCerts,
                        const CSSM_FIELD_PTR VerifyScope,
                        uint32 ScopeSize,
                        CSSM_TP_ACTION Action,
                        const CSSM_DATA_PTR Data,
                        CSSM_DATA_PTR *Evidence,
                        uint32 *EvidenceSize)

Input

TPHandle

The handle to the TP module to perform this operation.

NumberofPolicyIdentifiers

The number of policy identifiers provided in the PolicyIdentifiers parameter.

NumberofAnchorCerts

The number of anchor certificates provided in the AnchorCerts parameter.

CertToBeVerified

A pointer to the CSSM_CERTGROUP structure containing a certificate containing at least one signature for verification. An unsigned certificate template cannot be verified.

ScopeSize

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

Output

EvidenceSize

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.

Input/optional

CLHandle

The handle to the CL module that can be used to manipulate and parse the certgroup certificates and the certificates in the specified data stores. If no CL module is specified, the TP module uses an assumed CL module.

DBList

A list of handle pairs specifying a DL module and a data store managed by that module. These data stores should contain zero or more trusted certificates. If no data stores are specified, the TP module can assume a default data store, if required.

CSPHandle

The handle of a CSP that can be used for verification of the certificate chain.

PolicyIdentifiers

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

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 specifiable stopping conditions and their meaning are defined in Table 38.

Table 38. Specifiable Stopping Conditions

CSSM_TP_STOP_ON	Definitions
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_FAL	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.

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.

VerifyScope

A pointer to the CSSM_FIELD array containing the OID indicators specifying the certificate fields to be used in the verification process. If VerifyScope is not specified, the TP Module must assume a default scope (portions of each certificate) when performing the verification process.

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

Data

A pointer to the CSSM_DATA structure containing the application-specific data or a reference to the application-specific data upon which the requested action should be performed. If no data is specified, 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_DATA objects containing an audit trail of evidence constructed by the TP module during the verification process. Typically, this is a list of certificates and CRLs that were used to establish the validity of the CertToBeVerified, but other objects may be appropriate for other types of TPs.

CSSM_TRUE if the certificate group verified. CSSM_FALSE if the certificate did not verify or an error condition occurred. Use CSSM_GetError to obtain the error code.