TP_CertGroupPrune

NAME
  TP_CertGroupPrune,
  CSSM_TP_CertGroupPrune - Remove locally issued anchor
                           certificates (CDSA)

SYNOPSIS
  # include <cssm.h>

   API:
       CSSM_RETURN CSSMAPI CSSM_TP_CertGroupPrune
       (CSSM_TP_HANDLE TPHandle,
       CSSM_CL_HANDLE CLHandle,
       const CSSM_DL_DB_LIST *DBList,
       const CSSM_CERTGROUP *OrderedCertGroup,
       CSSM_CERTGROUP_PTR *PrunedCertGroup)
   SPI:
       CSSM_RETURN CSSMTPI TP_CertGroupPrune
       (CSSM_TP_HANDLE TPHandle,
       CSSM_CL_HANDLE CLHandle,
       const CSSM_DL_DB_LIST *DBList,
       const CSSM_CERTGROUP *OrderedCertGroup,
       CSSM_CERTGROUP_PTR *PrunedCertGroup)

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 the certgroup certificates and the
          certificates in the specified data stores. If no certificate
          library module is specified, the TP module uses an assumed CL
          module.

  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. The data stores are searched
          for anchor certificates restricted to have local scope. These
          certificates are candidates for removal from the subject
          certificate group.

  OrderedCertGroup (input)
          The initial complete set of semantically-related certificates -
          for example, the result of a CSSM_TP_CertGroupConstruct()
          (CSSM API), or TP_CertGroupConstruct() (TP SPI), call - from
          which certificates will be selectively removed.

  PrunedCertGroup (output)
          A pointer to a certificate group containing those
          certificates which are verifiable credentials outside of
          the local system. The CSSM_CERTGROUP and its substructure
          is allocated by the service provider and must be deallocated
          by the application.

DESCRIPTION
  This function removes any locally issued anchor certificates from a
  constructed certificate group. The prune operation can remove those
  certificates that have been signed by any local certificate authority,
  as it is possible that these certificates will not be meaningful on
  other systems.

  This operation can also remove additional certificates that can be
  added to the certificate group again using the
  CSSM_TP_CertGroupConstruct() (CSSM API), or TP_CertGroupConstruct()
  (TP SPI), operation. The pruned certificate group should be suitable
  for export to external hosts/entities, which can in turn reconstruct
  and verify the certificate group.

  The DBList parameter specifies a set of data stores containing
  certificates that should be pruned from 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_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_CertGroupConstruct
      CSSM_TP_CertGroupVerify

  Functions for the TP SPI:

      TP_CertGroupConstruct
      TP_CertGroupVerify