NAME

   CL_CertGroupFromVerifiedBundle,
   CSSM_CL_CertGroupFromVerifiedBundle - Verify the signature of a
                                         bundle (CDSA)

 SYNOPSIS

   # include <cssm.h>

        API:
        CSSM_RETURN CSSMAPI CSSM_CL_CertGroupFromVerifiedBundle
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CERT_BUNDLE *CertBundle,
        const CSSM_DATA *SignerCert,
        CSSM_CERTGROUP_PTR *CertGroup)
        SPI:
        CSSM_RETURN CSSMCLI CL_CertGroupFromVerifiedBundle
        (CSSM_CL_HANDLE CLHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CERT_BUNDLE *CertBundle,
        const CSSM_DATA *SignerCert,
        CSSM_CERTGROUP_PTR *CertGroup)

 LIBRARY

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

 PARAMETERS

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

   CCHandle (input/optional)
           The handle of the cryptographic context to control the
           verification operation.

   CertBundle (input)
           A structure containing a reference to a signed, encoded bundle
           of certificates and to descriptors of the type and encoding of
           the bundle.  The bundled certificates are to be separated into
           a certificate group (list of individual encoded certificates).
           If the bundle type and bundle encoding are not specified, the
           add-in module might either attempt to decode the bundle
           assuming a default type and encoding or might immediately fail.

   SignerCert (input/optional)
           The certificate to be used to verify the signature on the
           certificate bundle.  If the bundle is signed but this field is
           not specified, then the module will assume a default certificate
           for verification.

   CertGroup (output)
           A pointer to the certificate group, represented as an array
           of individual, encoded certificates. The certificate group
           and CSSM_CERTGROUP substructures are allocated by the serivce
           provider and must be deallocated by the application. The group
           contains all certificates contained in the certificate bundle.

 DESCRIPTION

   This function accepts as input a certificate bundle (a codified and
   signed aggregation of the certificates in the group), verifies the
   signature of the bundle (if a signature is present), and returns a
   certificate group (as an array of individual certificates) including
   every certificate contained in the bundle. The signature on the
   certificate aggregate is verified using the cryptographic context and
   possibly using the input signer certificate.  The CL module embeds the
   knowledge of the verification scope for the bundle types that it
   supports. A CL module's supported bundle types and encodings are
   available to applications by querying the CSSM registry. The type and
   encoding of the certificate bundle must be specified with the input
   bundle.  If signature verification is successful, the certificate
   aggregate will be parsed into a certificate group whose order
   corresponds to the certificate aggregate ordering. This certificate
   group will then be returned to the calling application.

 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_BUNDLE_POINTER
        CSSMERR_CL_INVALID_BUNDLE_INFO
        CSSMERR_CL_INVALID_CERT_POINTER
        CSSMERR_CL_INVALID_CERTGROUP_POINTER
        CSSMERR_CL_UNKNOWN_FORMAT

 SEE ALSO

   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_CL_CertGroupToSignedBundle

   Functions for the CLI SPI:

       CL_CertGroupToSignedBundle