TP_CertGroupConstruct(3)TP_CertGroupConstruct(3)NAME
TP_CertGroupConstruct, CSSM_TP_CertGroupConstruct - Construct creden‐
tial (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
CSSM_RETURN CSSMAPI CSSM_TP_CertGroupConstruct (CSSM_TP_HANDLE TPHan‐
dle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const
CSSM_DL_DB_LIST *DBList, const void *ConstructParams, const CSSM_CERT‐
GROUP *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 (libcssm.so)
PARAMETERS
The handle to the trust policy module to perform this operation. The
handle to the certificate library module that can be used to manipulate
and parse values in stored in the certgroup certificates. If no cer‐
tificate library module is specified, the TP module uses an assumed CL
module. 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. A list of han‐
dle 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. A pointer to data that can be used by the add-in trust policy
module in constructing the CertGroup.Thesemanticsofthisparameterarede‐
finedby the trust policy and the credential model supported by that
policy. The input parameter can consist of a set of values, each guid‐
ing 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. A
list of certificates that form a possibly incomplete set of certifi‐
cates. The first certificate in the group represents the target cer‐
tificate 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. A pointer to a com‐
plete certificate group based on the original subset of certificates
and the certificate data stores. The CSSM_CERTGROUP and its sub-struc‐
ture 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 certifi‐
cates from an end entity to a top level certification authority. The
constructed certificate group format (such as ordering) is implementa‐
tion specific. However, the subject or end-entity is always the first
certificate in the group.
A partially constructed certificate group is specified in Cert‐
GroupFrag. 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 relation‐
ship among them. The result set can be augmented by adding semanti‐
cally-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 cer‐
tificates, the function output is an uninterrupted, ordered chain of
certificates based on the first certificate as the leaf of the certifi‐
cate 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 certifi‐
cates 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_Cert‐
GroupVerify() (CSSM API), or TP_CertGroupVerify() (TP SPI).
The constructed certificate group can be consistent locally or glob‐
ally. 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 repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_TP_INVALID_CL_HANDLE CSS‐
MERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_INVALID_DL_HANDLE CSS‐
MERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSS‐
MERR_TP_INVALID_DB_LIST CSSMERR_TP_INVALID_CERTGROUP_POINTER CSS‐
MERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSS‐
MERR_TP_CERTGROUP_INCOMPLETE
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_TP_CertGroupPrune(3), CSSM_TP_CertGroupVerify(3)
Functions for the TP SPI:
TP_CertGroupPrune(3), TP_CertGroupVerify(3)TP_CertGroupConstruct(3)