CL_CertVerify

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