CPKIFPathProcessingMediator2 Class Reference

#include <CPKIFPathProcessingMediator2.h>

Inheritance diagram for CPKIFPathProcessingMediator2:

[legend]

Collaboration diagram for CPKIFPathProcessingMediator2:

[legend]

List of all members.

Detailed Description

CPKIFPathProcessingMediator2 implements three PKI-related interfaces: IPKIFPathValidate, IPKIFPathBuild, IPKIFPathBuildAndValidate and IPKIFDefaultPathManagement.

class CPKIFPathProcessingMediator2 : 
    public IPKIFMediator, 
    public IPKIFPathValidate, 
    public IPKIFPathBuild, 
    public IPKIFDefaultPathManagement

PKIF provides three colleague classes for use with CPKIFPathProcessingMediator2:

These colleagues provide functionality to build and validate certificate paths. See Associating an LDAP Directory with a CMS Object and Enabling OCSP for details on adding colleague objects.

TSP-enforcing: Yes

Definition at line 64 of file CPKIFPathProcessingMediator2.h.


Public Member Functions
	CPKIFPathProcessingMediator2 (bool addDefaultColleagues=false)
virtual	~CPKIFPathProcessingMediator2 ()
void	InitializeMediator (std::vector< CPKIFException * > *errorInfo)
void	Terminate ()
void	Initialize ()
void	GetColleagues (std::vector< IPKIFColleaguePtr > &v) const
void	AddColleague (IPKIFColleaguePtr &module)
bool	ValidatePath (CPKIFCertificatePath &path, CPKIFPathValidationResults &results, CPKIFFuncStoragePtr &thisCallOnlyFuncs)
void	SetAdditionalCertificateChecks (CPKIFFuncStoragePtr &funcs)
bool	BuildPath (CPKIFCertificatePath &path)
bool	BuildAndValidatePath (CPKIFCertificatePath &path, CPKIFPathValidationResults &results)
void	SetDefaultPathSettings (CPKIFPathSettingsPtr &pathSettings)
CPKIFPathSettingsPtr	GetDefaultPathSettings ()

Constructor & Destructor Documentation

CPKIFPathProcessingMediator2::CPKIFPathProcessingMediator2 ( bool addDefaultColleagues = false )

Interface: External

This function creates CPKIFPathProcessingMediator2 objects. If the addDefaultColleagues parameter is set to true the following colleagues CPKIFPathValidator2, CPKIFPathBuilder2 and CPKIFPathBuildAndValidate will be added to the mediator upon initialization. Following construction, CPKIFPathProcessingMediator2 instances are not ready for use. It is necessary to call Initialize prior to exercising any functionality.

Returns:: None

Parameters:

addDefaultColleagues

[in] Boolean value, if true will force Initialize to add default colleagues to the mediator.

Definition at line 71 of file CPKIFPathProcessingMediator2.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_PATH_MEDIATOR.

CPKIFPathProcessingMediator2::~CPKIFPathProcessingMediator2 ( void ) [virtual]

Interface: External

This function destroys CPKIFPathProcessingMediator2 objects.

Returns:: None

Definition at line 86 of file CPKIFPathProcessingMediator2.cpp.

References LOG_STRING_DEBUG, Terminate(), and TOOLKIT_PATH_MEDIATOR.

Member Function Documentation

void CPKIFPathProcessingMediator2::InitializeMediator ( std::vector< CPKIFException * > * errorInfo ) [virtual]

Interface: External

Initialize prepares an instance of CPKIFPathProcessingMediator2 for use, including initialization of all runtime-associated mediators and colleagues. If a boolean true was passed to CPKIFPathProcessingMediator2 constructor default colleagues CPKIFPathValidator2, CPKIFPathBuilder2 and CPKIFPathBuildAndValidate will be added. By default, all mediators catch and discard these exceptions and ignore the offending colleague. Applications can review the list of exceptions that occurred during initialization by passing a non-NULL pointer to a vector of CPKIFException objects. Any exception objects returned in the vector must be freed by the application.

Returns:: None

Exceptions:

CPKIFPathException(COMMON_ALREADY_INITIALIZED)

Parameters:

errorInfo

[in/out] Pointer to a vector to receive exceptions thrown by colleagues

Reimplemented from IPKIFColleague.

Definition at line 174 of file CPKIFPathProcessingMediator2.cpp.

References AddColleague(), COMMON_ALREADY_INITIALIZED, LOG_STRING_DEBUG, and TOOLKIT_PATH_MEDIATOR.

Referenced by Initialize().

void CPKIFPathProcessingMediator2::Terminate ( ) [virtual]

Interface: External

Terminate de-initializes an instance of CPKIFPathProcessingMediator2 rendering it unusable until after a subsequent call to Initialize. Terminate will remove all mediator and colleague associations and will destroy any colleagues associated at runtime via AddColleague with transfer of ownership.

Returns:: None

Reimplemented from IPKIFColleague.

Definition at line 105 of file CPKIFPathProcessingMediator2.cpp.

References _ASSERT, COMMON_TERMINATION_ERROR, LOG_STRING_DEBUG, LOG_STRING_ERROR, IPKIFColleague::RemoveMediatorAssociations(), RemoveParentRelationships(), IPKIFColleague::Terminate(), and TOOLKIT_PATH_MEDIATOR.

Referenced by ~CPKIFPathProcessingMediator2().

void CPKIFPathProcessingMediator2::Initialize ( void ) [virtual]

Interface: External

Initialize prepares an instance of CPKIFPathProcessingMediator2 for use, including initialization of all runtime-associated mediators and colleagues. If a boolean true was passed to CPKIFPathProcessingMediator2 constructor default colleagues CPKIFPathValidator2, CPKIFPathBuilder2 and CPKIFPathBuildAndValidate will be added.

Returns:: None

Exceptions:

CPKIFPathException(COMMON_ALREADY_INITIALIZED)

Reimplemented from IPKIFColleague.

Definition at line 155 of file CPKIFPathProcessingMediator2.cpp.

References InitializeMediator().

void CPKIFPathProcessingMediator2::GetColleagues ( std::vector< IPKIFColleaguePtr > & v ) const

Interface: External

This function is used retrive all the colleagues associated with this instance

Returns:: None

Parameters:

v	[out] std::vector that will contain all the colleagues assosiated with this instance

Definition at line 647 of file CPKIFPathProcessingMediator2.cpp.

Referenced by SavePathProcessingComponents().

void CPKIFPathProcessingMediator2::AddColleague ( IPKIFColleaguePtr & module )

Interface: External

This function associates a colleague at runtime. When invoked with transferOwnership equal to true, the colleague specified by the module parameter will be destroyed when Terminate is invoked.

Only colleagues that implement at least one interface of the associated mediator should be passed to AddColleague. Adding unrelated colleagues to a collection held by a mediator will decrease performance.

Returns:: None

Parameters:

module

[in] Pointer to an IPKIFColleague object

Definition at line 216 of file CPKIFPathProcessingMediator2.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_PATH_MEDIATOR.

Referenced by InitializeMediator(), and LoadPathProcessingComponents().

bool CPKIFPathProcessingMediator2::ValidatePath	(	CPKIFCertificatePath &	path,
		CPKIFPathValidationResults &	results,
		CPKIFFuncStoragePtr &	thisCallOnlyFuncs
	)			`[virtual]`

Interface: External

This function will iterate over all associated colleagues that implement the IPKIFPathValidate interface attempting to validate path until a colleague that returns true (i.e. indicates that a definitive determination was made) is found. A definitive determination may include failure of any checks (basic path validation, signature verification failure, revocation status failure, etc.). If no colleague returns a definitive result a partial result may be returned, for example when revocation data is not available. If no colleague is found that implements the IPKIFPathValidate interface an exception is thrown.

At present, PKIF provides a single colleague for validation so the iterative nature of this function is not exercised. The iterative structure is intended to support future efforts involving server-based validation.

The Boolean returned by ValidatePath indicates whether a determination was made (and exists to maintain consistency with direct usage of a path validation colleague). It does NOT indicate the outcome of validation. To determine if path validation was entirely successful invoke the PathSuccessfullyValidated function on the results object.

Returns:: This function returns a Boolean value indicating whether a definitive answer could be determined. For example, if a path can be declared completely valid, including revocation status determination for all certificates, the function returns true. If a path can be declared invalid, due to a failure of a basic validation check or due to a revoked certificate, then the function returns true. If the validation operation cannot be completed, e.g. because some revocation information is not available, then this function returns false. The return value is primarily of interest to the associated mediator, which would consult another validation colleague upon lack of a definitive response. Detailed results of the path validation operation are available via the results parameter.

Exceptions:

	CPKIFPathException(COMMON_INVALID_INPUT)
	CPKIFPathException(COMMON_UNSUPPORTED_ALG)
	CPKIFPathException(COMMON_MEDIATOR_MISSING)
	CPKIFPathException(COMMON_OPERATION_NOT_HANDLED)
	CPKIFCacheException(CACHE_CERT_STORE_OPEN_FAILED)
	CPKIFCryptoException(COMMON_INVALID_INPUT)
	CPKIFCryptoException(PKIFCAPI_VERIFY_FAILED)
	CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED)
	CPKIFException(COMMON_NOT_IMPLEMENTED)
	CPKIFException(COMMON_INVALID_INPUT)

Parameters:

path	[in] Reference to a CPKIFCertificatePath object containing the certification path to validate
results	[out] Reference to a CPKIFPathValidationResults object containing the results of a validation operation
thisCallOnlyFuncs	[out] Pointer to a CPKIFFuncStorage containing the application-defined checks to invoke during path validation

Implements IPKIFPathValidate.

Definition at line 353 of file CPKIFPathProcessingMediator2.cpp.

References AuditPathEvent(), AuditString, CAT_PKIF_PATH, COMMON_OPERATION_NOT_HANDLED, COMMON_UNKNOWN_ERROR, GetDefaultPathSettings(), CPKIFCertificatePath::GetPathSettings(), LOG_STRING_DEBUG, CPKIFPathLogger::LogPath(), CPKIFPathLogger::LogValidationResults(), PKIF_UNEXPECTED_EXCEPTION, PO_VALIDATE, CPKIFException::print(), CPKIFCertificatePath::SetPathSettings(), and TOOLKIT_PATH_MEDIATOR.

void CPKIFPathProcessingMediator2::SetAdditionalCertificateChecks ( CPKIFFuncStoragePtr & funcs ) [virtual]

Interface: External

This function can be used to associate custom checks that will be applied to certificates during path validation. It takes a pointer to a Functor object and an indication of Functor ownership. The functor object must point to one or more functions that take three parameters and return a void.

The pointer passed to this function will override previously set values. Functors must be constructed by the application prior to calling this function, i.e. this function will not accumulate functions. Care must be taken to avoid overriding intended functionality. Care must also be taken to ensure that either ownership of the functor is transferred or the scope of the functor is guaranteed to be greater than that of the mediators/colleagues using the functor.

Returns:: None

Exceptions:

	CPKIFPathException(COMMON_OPERATION_NOT_HANDLED)
	CPKIFPathException(COMMON_OPERATION_NOT_SUCCESSFUL)

Parameters:

funcs

[in] Pointer to a CPKIFFuncStoragePtr containing the application-defined checks to invoke during path validation

Implements IPKIFPathValidate.

Definition at line 427 of file CPKIFPathProcessingMediator2.cpp.

References AuditString, CAT_PKIF_PATH, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), and TOOLKIT_PATH_MEDIATOR.

bool CPKIFPathProcessingMediator2::BuildPath ( CPKIFCertificatePath & path ) [virtual]

Interface: External

This function will iterate over all associated colleagues that implement the IPKIFPathBuild interface attempting to validate a path until a colleague that returns true (i.e. a path was found). If no colleague is found that can build a path, false is returned. If no colleague is found that implements the IPKIFPathBuild interface, an exception is thrown. As shown in the sample code, this function may be called iteratively in conjunction with the ValidatePath function to build and validate certificate paths.

At present, PKIF provides a single colleague for path building so the iterative nature of this function is not exercised. The iterative structure is intended to support future efforts involving server-based validation.

The path parameter must identify the target certificate for the path development operation. If the path parameter contains path settings, those path settings will be used. If the path parameter does not contain path settings, the default path settings associated with the mediator via a call to SetDefaultPathSettings will be used, if present. If no default path settings are available and no path settings are associated with the path parameter, an empty CPKIFPathSettings object will be created and used throughout path development.

The path parameter is used to maintain state across iterative calls to BuildPath. A state object will be included in the path object upon the first invocation and updated upon subsequent calls. A CPKIFBuilderStatistics object will also be created and stored in the path object upon the first call and updated upon subsequent calls.

This function requires access to the following interfaces from the collection of associated mediators and will fail if any are not available: IPKIFTrustCache and IPKIFCertRepository. The following interfaces will be used, if present, but are not required for operation: IPKIFCertRepositoryUpdate and IPKIFCRLRepository.

Returns:: This function returns true when an invocation of the function was successful, e.g. a certification path was found, and false when a certification path could not be found.

Exceptions:

	CPKIFPathException(COMMON_MEDIATOR_MISSING)
	CPKIFPathException(COMMON_OPERATION_NOT_HANDLED)
	CPKIFPathException(COMMON_INVALID_INPUT)
	CPKIFCacheException(CACHE_LDAP_ERROR)
	CPKIFCacheException(CACHE_PARSE_ERROR)
	CPKIFCacheException(CACHE_UPDATE_FAILED)
	CPKIFCacheException(COMMON_NOT_INITIALIZED)
	CPKIFCacheException(COMMON_OPERATION_NOT_SUCCESSFUL)
	CPKIFException(COMMON_INVALID_INPUT)

Parameters:

path

[in/out] A reference to a CPKIFCertificatePath object containing information necessary to perform a certification path development operation

Implements IPKIFPathBuild.

Definition at line 503 of file CPKIFPathProcessingMediator2.cpp.

References AuditPathEvent(), AuditString, CAT_PKIF_PATH, COMMON_OPERATION_NOT_HANDLED, COMMON_OPERATION_NOT_SUCCESSFUL, COMMON_UNKNOWN_ERROR, GetDefaultPathSettings(), CPKIFCertificatePath::GetPathSettings(), LOG_STRING_DEBUG, PKIF_UNEXPECTED_EXCEPTION, PO_BUILD, CPKIFException::print(), CPKIFCertificatePath::SetPathSettings(), and TOOLKIT_PATH_MEDIATOR.

bool CPKIFPathProcessingMediator2::BuildAndValidatePath	(	CPKIFCertificatePath &	path,
		CPKIFPathValidationResults &	results
	)			`[virtual]`

Interface: External

This function will iterate over all associated colleagues that implement the IPKIFPathBuildAndValidate interface. Currently, only the CPKIFPathBuildAndValidate colleague class provides an implementation of this interface. It implements iterative invocation of the available IPKIFPathBuild and IPKIFPathValidate functionality (provided by the CPKIFPathBuilder2 and CPKIFPathValidator2 classes, by default).

The certificate and CRL sources consulted during path processing vary depending on the colleague objects associated with the mediator(s) associated with the instance of CPKIFPathProcessingMediator2 on which this function is implemented.

The path parameter must identify the target certificate for the path development operation. If the path parameter contains path settings, those path settings will be used. If the path parameter does not contain path settings, the default path settings associated with the mediator via a call to SetDefaultPathSettings will be used, if present. If no default path settings are available and no path settings are associated with the path parameter, an empty CPKIFPathSettings object will be created and used throughout path development.

Unlike the IPKIFValidate::ValidatePath function, BuildAndValidatePath does not provide a parameter for applications to handle critical extensions not used during path building or validation. A handler is provided to permit any value in a critical key usage extension. If an application must process certification paths featuring private critical extensions, it must use the IPKIFValidate::ValidatePath interface.

Returns:: This function returns a Boolean value indicating whether a definitive answer could be determined.

Exceptions:

CPKIFPathException(COMMON_OPERATION_NOT_HANDLED)

Parameters:

path

[in/out] Reference to a CPKIFCertificatePath object containing, minimally, the target certificate when the function is called and the completed path, if path processing was successfully, upon return. The object returned via this parameter is complete only if no exception is thrown. If an exception is thrown, the object may be useful for diagnostic purposes, e.g. to review path building statistics, but may be incomplete.

results

[out] Reference to a CPKIFPathValidationResults object used to return the results of a path validation operation. The object returned via this parameter is valid only path validation was attempted (i.e., the m_nReturnedPaths member of the CPKIFBuilderStatistics object is not 0). If an exception is thrown, the object may be useful for diagnostic purposes, e.g. if one or more paths were found but failed validation. If no paths could be developed from the target certificate to a trust anchor and validation was not attempted, the object returned via results will simply contain default values.

Implements IPKIFPathBuildAndValidate.

Definition at line 582 of file CPKIFPathProcessingMediator2.cpp.

References AuditString, CAT_PKIF_PATH, COMMON_OPERATION_NOT_HANDLED, COMMON_UNKNOWN_ERROR, GetDefaultPathSettings(), CPKIFCertificatePath::GetPathSettings(), LOG_STRING_DEBUG, CPKIFPathLogger::LogPath(), PKIF_UNEXPECTED_EXCEPTION, CPKIFException::print(), CPKIFCertificatePath::SetPathSettings(), and TOOLKIT_PATH_MEDIATOR.

void CPKIFPathProcessingMediator2::SetDefaultPathSettings ( CPKIFPathSettingsPtr & pathSettings ) [virtual]

Interface: External

The SetDefaultPathSetting function takes a reference to a smart pointer to a CPKIFPathSettings object containing default settings and sets the object as the default. The default settings will be applied to future calls to BuildPath or ValidatePath on the mediator assigned the default settings object when settings are not explicitly set on the path object.

Returns:: None

Parameters:

pathSettings

[in] Reference to a smart pointer to a CPKIFPathSettings object containing the path settings that should serve as the default path settings for path validation operations performed using the associated mediator.

Implements IPKIFDefaultPathManagement.

Definition at line 265 of file CPKIFPathProcessingMediator2.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_PATH_MEDIATOR.

CPKIFPathSettingsPtr CPKIFPathProcessingMediator2::GetDefaultPathSettings ( ) [virtual]

Interface: External

The GetDefaultPathSetting function returns a pointer to a CPKIFPathSettings object containing default settings. If no default settings object has been specified NULL is returned.

Returns:: The GetDefaultPathSettings function returns a pointer to the default CPKIFPathSettings object or NULL if no default path settings have been specified.

Implements IPKIFDefaultPathManagement.

Definition at line 286 of file CPKIFPathProcessingMediator2.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_PATH_MEDIATOR.

Referenced by BuildAndValidatePath(), BuildPath(), and ValidatePath().

The documentation for this class was generated from the following files:

CPKIFPathProcessingMediator2 Class Reference

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation