 |
Index for
Section 3 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
TP_CertGroupConstruct(3)
NAME
TP_CertGroupConstruct, CSSM_TP_CertGroupConstruct - Construct credential
(CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
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 (libcssm.so)
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.Thesemanticsofthisparameteraredefinedby 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_intro(3).
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_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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|