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);
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.
- 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.
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.
Invalid certificate group structure.
Signer certificate is not signer of subject.
Signature can't be trusted.
Unable to verify certificate.
Invalid action data specified for action.
Unable to determine trust for action.
An anchor certificate could not be identified.
Function not implemented.