NAME
   TP_CertGroupConstruct,
   CSSM_TP_CertGroupConstruct - Construct credential (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_TP_CertGroupConstruct
        (CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_DL_DB_LIST *DBList,
        const void *ConstructParams,
        const CSSM_CERTGROUP *CertGroupFrag,
        CSSM_CERTGROUP_PTR *CertGroup)
    SPI:
        CSSM_RETURN CSSMTPI TP_CertGroupConstruct
        (CSSM_TP_HANDLE TPHandle,
        CSSM_CL_HANDLE CLHandle,
        CSSM_CSP_HANDLE CSPHandle,
        const CSSM_DL_DB_LIST *DBList,
        const void *ConstructParams,
        const CSSM_CERTGROUP *CertGroupFrag,
        CSSM_CERTGROUP_PTR *CertGroup)

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

 PARAMETERS
   TPHandle (input)
           The handle to the trust policy module to perform this
           operation.

   CLHandle (input/optional)
           The handle to the certificate library module that can be used
           to manipulate and parse values in stored in the certgroup
           certificates. If no certificate library module is specified,
           the TP module uses an assumed CL module.

   CSPHandle (input./optional)
           A handle specifying the Cryptographic Service Provider to be
           used to verify certificates as the certificate group is
           constructed. If the a CSP handle is not specified, the trust
           policy module can assume a default CSP. If the module cannot
           assume a default, or the default CSP is not available on the
           local system, an error occurs.

   DBList (input)
           A list of handle pairs specifying a data storage library
           module and a data store, identifying certificate databases
           containing certificates (and possibly other security objects)
           that are managed by that module. certificates (and possibly
           other security objects).  The data stores should be searched
           to complete construction of a semantically-related certificate
           group.

   ConstructParams (input/optional)
           A pointer to data that can be used by the add-in trust
           policy module in constructing the CertGroup.  The semantics
           of this parameter are defined by the trust policy and the
           credential model supported by that policy. The input
           parameter can consist of a set of values, each guiding some
           aspect of the construction process. Parameter values can:

             · Limit the certificates that are added to the constructed
               set.

             · Identify other sources of certificates for inclusion in
               the constructed set.

   CertGroupFrag (input)
           A list of certificates that form a possibly incomplete
           set of certificates. The first certificate in the group
           represents the target certificate for which a group of
           semantically related certificates will be assembled.
           Subsequent intermediate certificates can be supplied by
           the caller.  They need not be in any particular order.

   CertGroup (output)
           A pointer to a complete certificate group based on the
           original subset of certificates and the certificate data
           stores. The CSSM_CERTGROUP and its sub-structure is
           allocated by the service provider and must be deallocated
           by the application.

 DESCRIPTION
   This function builds a collection of certificates that together
   make up a meaningful credential for a given trust domain. For
   example, in a hierarchical trust domain, a certificate group is a
   chain of certificates from an end entity to a top level certification
   authority. The constructed certificate group format (such as
   ordering) is implementation specific.  However, the subject or
   end-entity is always the first certificate in the group.

   A partially constructed certificate group is specified in
   CertGroupFrag.  The first certificate is interpreted to be the
   subject or end-entity certificate. Subsequent certificates in
   the CertGroupFrag structure may be used during the construction
   of a certificate group in conjunction with certificates found in
   the data stores specified in DBList. The trust policy defines the
   certificates that will be included in the resulting set.

   The output set is a sequence of certificates ordered by the
   relationship among them. The result set can be augmented by adding
   semantically-related certificates obtained by searching the
   certificate data stores specified in DBList. The data stores are
   searched in order of appearance in DBList. If the TP supports a
   hierarchical model of certificates, the function output is an
   uninterrupted, ordered chain of certificates based on the first
   certificate as the leaf of the certificate chain. If the certificate
   is multiply-signed, then the ordered chain will follow the first
   signing certificate.  The function should also detect cross-
   certificate pairs and should include both certificates without
   duplicating either certificate.

   Extraneous certificates in the CertGroupFrag fragment or contained
   in the DBList data stores are ignored. The certificate group returned
   by this function can be used as input to the function
   CSSM_TP_CertGroupVerify() (CSSM API), or TP_CertGroupVerify() (TP SPI).

   The constructed certificate group can be consistent locally or
   globally.  Consistency can be limited to the local system if locally-
   defined points of trust are inserted into the group.

 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_TP_INVALID_CL_HANDLE
        CSSMERR_TP_INVALID_CSP_HANDLE
        CSSMERR_TP_INVALID_DL_HANDLE
        CSSMERR_TP_INVALID_DB_HANDLE
        CSSMERR_TP_INVALID_DB_LIST_POINTER
        CSSMERR_TP_INVALID_DB_LIST
        CSSMERR_TP_INVALID_CERTGROUP_POINTER
        CSSMERR_TP_INVALID_CERTGROUP
        CSSMERR_TP_INVALID_CERTIFICATE
        CSSMERR_TP_CERTGROUP_INCOMPLETE

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_TP_CertGroupPrune
       CSSM_TP_CertGroupVerify

   Functions for the TP SPI:

       TP_CertGroupPrune
       TP_CertGroupVerify