NAME

TP_CertGroupConstruct

SYNOPSIS

CSSM_CERTGROUP_PTR CSSMTPI TP_CertGroupConstruct

    (CSSM_TP_HANDLE TPHandle,
    CSSM_CL_HANDLE CLHandle,
    CSSM_CSP_HANDLE CSPHandle,
    const CSSM_DL_DB_LIST_PTR DBList,
    CSSM_CERTGROUP_PTR CertGroupFrag)

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 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.

PARAMETERS

TPHandle (input)

The handle that describes the add-in trust policy module used to perform this function.

CLHandle (input)

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

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 certificate databases containing certificates that may be used to construct the trust structure of the subject certificate group.

CertGroupFrag (input)

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.

RETURN VALUE

A CSSM_CERTGROUP_PTR return value contains a pointer to a valid certificate group. When NULL is returned an error has occurred. This function can also return errors specific to CL and DL modules.

ERRORS

CSSM_INVALID_TP_HANDLE

Invalid handle.

CSSM_INVALID_CL_HANDLE

Invalid handle.

CSSM_INVALID_DL_HANDLE

Invalid handle.

CSSM_INVALID_DB_HANDLE

Invalid handle.

CSSM_TP_INVALID_CERTIFICATE

Invalid certificate.

CSSM_TP_CERTGROUP_NOT_FOUND

Unable to construct meaningful cert group.

CSSM_FUNCTION_NOT_IMPLEMENTED

Function not implemented.

SEE ALSO

TP_CertGroupPrune, TP_CertVerify