TP_CertGroupConstruct

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

TP_CertGetAllTemplateFields

TP_CertGroupPrune

TP_CertGroupConstruct

Library
Description
Errors

Parameters
Return Value
See Also

NAME

TP_CertGroupConstruct: CSSM_TP_CertGroupConstruct - Construct credential (CDSA)

SYNOPSIS

# include <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 (cdsa$incssm300_shr.exe)

PARAMETERS

`TPHandle` (input)
		The handle to the trust policy module to performthis operation.
`CLHandle` (input/optional)
		The handle to the certificate library module thatcan be used to manipulate and parse values in stored in the certgroupcertificates. If no certificate library module is specified, the TPmodule uses an assumed CL module.
`CSPHandle` (input./optional)
		A handle specifying the Cryptographic Service Providerto be used to verify certificates as the certificate group is constructed.If the a CSP handle is not specified, the trust policy module canassume a default CSP. If the module cannot assume a default, orthe default CSP is not available on the local system, an error occurs.
`DBList` (input)
		A list of handle pairs specifying a data storagelibrary module and a data store, identifying certificate databasescontaining certificates (and possibly other security objects) thatare managed by that module. certificates (and possibly other securityobjects). The data stores should be searched to complete constructionof a semantically-related certificate group.
`ConstructParams` (input/optional)
		A pointer to data that can be used by the add-intrust policy module in constructing the `CertGroup`.`The`semantics`of`this`parameter`are`defined`bythe trust policy and the credential model supported by that policy.The input parameter can consist of a set of values, each guidingsome aspect of the construction process. Parameter values can: Limit the certificates that are addedto the constructed set. Identify other sources of certificates for inclusionin the constructed set.
`CertGroupFrag` (input)
		A list of certificates that form a possibly incompleteset of certificates. The first certificate in the group representsthe target certificate for which a group of semantically related certificateswill be assembled. Subsequent intermediate certificates can be suppliedby the caller. They need not be in any particular order.
`CertGroup` (output)
		A pointer to a complete certificate group basedon the original subset of certificates and the certificate datastores. The CSSM_CERTGROUP and its sub-structure is allocated bythe service provider and must be deallocated by the application.

DESCRIPTION

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

A partially constructed certificate group is specified in CertGroupFrag.The first certificate is interpreted to be the subject or end-entitycertificate. Subsequent certificates in the CertGroupFrag structuremay be used during the construction of a certificate group in conjunctionwith certificates found in the data stores specified in DBList.The trust policy defines the certificates that will be includedin the resulting set.

The output set is a sequence of certificates ordered by therelationship among them. The result set can be augmented by addingsemantically-related certificates obtained by searching the certificatedata stores specified in DBList. The data storesare searched in order of appearance in DBList.If the TP supports a hierarchical model of certificates, the functionoutput is an uninterrupted, ordered chain of certificates based onthe first certificate as the leaf of the certificate chain. If thecertificate is multiply-signed, then the ordered chain will followthe first signing certificate. The function should also detect cross-certificatepairs and should include both certificates without duplicating eithercertificate.

Extraneous certificates in the CertGroupFrag fragmentor contained in the DBList data stores are ignored. Thecertificate group returned by this function can be used as inputto the function CSSM_TP_CertGroupVerify() (CSSM API), or TP_CertGroupVerify() (TP SPI).

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

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particularerror condition. The value CSSM_OK indicates success. All othervalues represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_TP_INVALID_CL_HANDLECSSMERR_TP_INVALID_CSP_HANDLECSSMERR_TP_INVALID_DL_HANDLECSSMERR_TP_INVALID_DB_HANDLECSSMERR_TP_INVALID_DB_LIST_POINTERCSSMERR_TP_INVALID_DB_LISTCSSMERR_TP_INVALID_CERTGROUP_POINTERCSSMERR_TP_INVALID_CERTGROUPCSSMERR_TP_INVALID_CERTIFICATECSSMERR_TP_CERTGROUP_INCOMPLETE