NAME

   CL_CertVerify,
   CSSM_CL_CertVerify - Verify a signed certificate (CDSA)

 SYNOPSIS

   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_CL_CertVerify
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *CertToBeVerified,
        const CSSM_DATA *SignerCert,
        const CSSM_FIELD *VerifyScope,
        uint32 ScopeSize)

    SPI:
        CSSM_RETURN CSSMAPI CSSM_CL_CertVerify
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *CertToBeVerified,
        const CSSM_DATA *SignerCert,
        const CSSM_FIELD *VerifyScope,
        uint32 ScopeSize)

 LIBRARY

   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 PARAMETER

 CLHandle (input)
           The handle that describes the add-in certificate
           library module used to perform this function.

   CCHandle (input/optional)
           The handle that describes the context of this cryptographic
           operation.

   CertToBeVerified (input)

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

   SignerCert (input/optional)
           A pointer to the CSSM_DATA structure containing the
           certificate used to sign the subject certificate. This
           certificate provides the public key to use in the
           verification process and if the certificate being
           verified contains multiple signatures, the signer's
           certificate indicates which signature is to be
           verified.

   VerifyScope (input/optional)
           A pointer to the CSSM_FIELD array containing the
           tag/value  pairs of the fields to be used in verifying
           the signature. (This should include all fields that
           were used to calculate the signature.) If the verify
           scope is null, the certificate library module assumes
           that its default set of certificate fields were used to
           calculate the signature, and those same fields are used
           in the verification process.

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

 DESCRIPTION

   This function verifies that the signed certificate has not been altered
   since it was signed by the designated signer. Only one signature is
   verified by this function. If the certificate to be verified includes
   multiple signatures, this function must be applied once for each
   signature to be verified. This function verifies a digital signature
   over the certificate fields specified by VerifyScope. If the
   verification scope fields are not specified, the function performs
   verification using a preselected set of fields in the certificate.

   The caller can specify a Cryptographic Service Provider (CSP) and
   verification algorithm that the CL can use to perform the verification.
   The handle for the CSP is contained in the cryptographic context
   identified by CCHandle.

   The verification process requires that the caller must specify the
   necessary verification algorithm parameters. These parameter values
   are specified in one of two locations:

     ·  As a field value in the SignerCert parameter

     ·  As a set of algorithm parameters contained in the cryptographic
        context identified by CCHandle

   If both of the preceding arguments are supplied, a consistency check
   is performed to ensure that they result in the same verification
   algorithm parameters. If they are not consistent, an error is returned.
   If only one of the above arguments is supplied, that argument is used
   to generate the verification algorithm parameters. If no algorithm
   parameters are found, the certificate cannot be verified and the
   operation fails.

 RETURN VALUE

   A CSSM_RETURN value indicating success or specifying a particular
   error condition. The value CSSM_OK indicates success. All other values
   represent an error condition.

 ERRORS

   Errors are described in the CDSA technical standard.  See CDSA.

        CSSMERR_CL_INVALID_CONTEXT_HANDLE
        CSSMERR_CL_INVALID_CERT_POINTER
        CSSMERR_CL_UNKNOWN_FORMAT
        CSSMERR_CL_INVALID_FIELD_POINTER
        CSSMERR_CL_UNKNOWN_TAG
        CSSMERR_CL_INVALID_SCOPE
        CSSMERR_CL_INVALID_NUMBER_OF_FIELDS
        CSSMERR_CL_SCOPE_NOT_SUPPORTED
        CSSMERR_CL_VERIFICATION_FAILURE

 SEE ALSO

   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_CL_CertSign

   Functions for the CLI SPI:

       CL_CertSign