Mediator/Colleague overview

PKIFv2 provides a framework exercising PKI-related functionality. This is achieved by a variation of the Mediators design pattern described in the Gang of Four’s Design Patterns book. The core PKI functionality provided by PKIFv2 is divided into several subsystems, each of which is serviced by a mediator object. These subsystems and their associated mediator objects are described in the following table.

Mediators do not directly implement any PKI functionality. Instead, mediators serve as containers for colleague objects that implement one or more of the interfaces implemented by a mediator object. The servicing of requests varies based on the colleagues associated with a mediator at a given point in time. For example, assume there is an instance of CPKIFCacheMediator2 with associated colleagues that provide an interface to a local certificate and CRL store. When the mediator is queried for CRL associated with a given certificate, the local store is checked and zero or more CRLs returned. If an LDAP colleague is added to the set of colleagues associated with the mediator (via a call to AddColleague) subsequent queries will consult the LDAP directory in addition to the local certificate store, as necessary. This permits environmental components to vary. Internal source code accesses functionality via interfaces implemented by a mediator.

Colleagues can be associated with a mediator at runtime. It is important that a collection of mediators and colleagues be complete for the desired usage. The Colleague interfaces and interface dependencies topic describes the interface dependencies for each of the PKIF-provided mediator and colleague objects.

Internally, mediators and colleagues are also used to organize handlers for certificate extension and CMS attribute parsing. Currently, these mediators are not exposed such that applications can impact their usage by PKIFv2.

Defining a PKI environment

Mediators and colleagues define the PKI environment of an application using PKIFv2. One application may elect to use the Microsoft CAPI certificate and CRLs stores exclusively, while another may augment CAPI with one or more LDAP directories (and possibly by including support for automatic population of CAPI stores with certificates and CRLs retrieved from remote sources). The primary components that vary are those related to certificate and CRL storage and retrieval and those related to revocation status checking. The components that provide cryptographic support utilize Microsoft CAPI or Netscape Security Services, which provides alternative means of varying the environment (e.g. through support for hardware cryptographic modules). Path processing logic and cryptographic support does not typically vary from application to application, thus the default path processing and cryptographic colleagues are generally sufficient.

Mediator/colleague configuration

This section describes the various mediators and colleague associated with each functional area. Definition of mediator/colleague collections is critical to the meeting an applications PKE needs. PKIFv2 features additional security-relevant functionality that is not implemented as mediators and colleagues, including the following:

·   ·   CMS support (uses mediators/colleagues for low-level functionality)

·   ·   ASN.1 encoding/decoding (X.509 objects, CMS object, TSP objects, etc.)

Certificate and CRL storage and retrieval

The certificate and CRL storage and retrieval functional category, referred to here and throughout the source code as the cache subcomponent, features the most colleague objects of any of the security-critical functional categories. The primary customer of the cache subcomponent functionality is the certification path processing and revocation status determination subcomponents. It is anticipated that all of the CAPI-related colleagues and the CRL DP retrieval colleagues will always be used in support of certificate path processing efforts. Additionally, it is anticipated that the in-memory certificate and CRL colleagues, or application-defined replacements, will also be used.

 
Unlike the path processing and revocation status mediators, the ordering in which colleagues are presented to a cache mediator instance is relatively unimportant. The cache mediator always consults all associated colleagues when servicing an application request. The requests typically have a parameter that indicates the types of information sources that should be consulted, e.g. local or remote sources. The mediator queries all colleagues, which elect to handle a request or not depending on the type of source that is targeted.

 
The following diagram shows two typical colleague collections to provide certificate and CRL storage and retrieval functionality. The first collection is the default, e.g. the collection created when true is passed to the CPKIFCacheMediator2 constructor.

Figure 1 Common combinations of certificate and CRL storage and retrieval-related colleagues using NSS store

Figure 2 Common combinations of certificate and CRL storage and retrieval-related colleagues using CAPI store

Cryptography

The cryptography functional category features two colleague classes: CPKIFCAPI2 and CPKIFCAPIRaw. These classes handle requests that operate on stored key material and in-memory key material, respectively, using a cryptographic service provider (CSP) registered with the Microsoft Crypto API (CAPI).

 The cryptography functional category features two colleague classes: CPKIFNSS and CPKIFNSSRaw. These classes handle requests that operate on stored key material and in-memory key material, respectively, using NSS.

By default, the CPKIFCAPI2 class will operate using any key stored in any available cryptographic service provider. The CPKIFCAPIRaw class always uses the default cryptographic service provider (except when creating a temporary key used to encrypt symmetric keys to be passed to CAPI, in which case an enhanced Microsoft CSP is used).

The following diagram shows two possible colleague collections. The second collection is the most commonly used option and is the default, e.g. the collection created when true is passed to the CPKIFCryptoMediator2 constructor.

Figure 3 Common combinations of cryptography-related colleagues using CAPI

Figure 4 Common combinations of cryptography-related colleagues using NSS

Certification path processing

The certification path processing functional category features three colleague objects, one of which is implemented in terms of the other two: CPKIFPathBuilder2, CPKIFPathValidator2 and CPKIFPathBuildAndValidate. The CPKIFPathBuildAndValidate simply iteratively invokes instances of CPKIFPathBuilder2 and CPKIFPathValidator2 until a decision can be reached for a target certificate or no additional candidate paths exist. It is essentially a placeholder until such time that an SCVP colleague is implemented.

The path processing category is the highest level of the security-critical categories as it relies on each of the other categories for service. The following diagram shows two possible collections. The second collection is the most commonly used option and is the default, e.g. the collection created when true is passed to the CPKIFPathProcessingMediator2 constructor.

Figure 5 Common combinations of path processing-related colleagues

Revocation status determination

For example, there is a single interface associated with the certificate revocation status determination functional category, IPKIFRevocationStatus. This interface is implemented by a mediator class, CPKIFRevocationStatusMediator2, and by two colleague classes, CPKIFX509CRLChecker and CPKIFOCSPChecker. These colleague objects can be associated with the mediator class in a variety of ways. The OCSP colleague class can be configured to consult a local OCSP responder, e.g. one that is explicitly trusted, or configured to check responders identified by an AIA extension in a certificate. A mediator may be configured with 0 to n OCSP colleagues that consult a local responder, 0 or 1 OCSP colleagues that consult AIA-specified responders and 0 or 1 CRL colleagues. The mediator class will query colleagues in the order they were presented to the mediator until a colleague is found that can satisfy the request or there are no more colleagues to query. Thus, the order in which colleague objects are introduced to a revocation status mediator is an important performance consideration. The following diagram shows several possible configurations.

The following diagram shows three possible collections. The first collection is the most commonly used option and is the default, e.g. the collection created when true is passed to the CPKIFRevocationStatusMediator2 constructor.

Figure 6 Common combinations of revocation status-related colleagues

Summary

The above sections describe the association of colleague objects with mediator objects. Mediators are, in turn, associated with each other. The collection of mediators can then be referenced by applications via the IPKIFMediatorPtr of any mediator object in the collection to obtain service.

Mediators are connected to each other at runtime via a call to AddMediator. It is through these connections that functionality from a peer functional category is exercised by a colleague object associated with a mediator. When a colleague instance requires access to a security function, it asks any mediator in its mediator collection for a pointer to the necessary interface. If the mediator supports that interface, it tries to fulfill the request. If it does not, it queries associated mediators for the interface until a mediator that implements the interface is found or there are no more mediators to query. In this way, mediators serve to decouple invocation of functionality from implementation of functionality and enable dynamic combinations of service implementations to be assembled and used.

The following diagram shows a collection of mediator and colleague objects. The application obtains service via an IPKIFMediatorPtr, which can point to any of the four mediator objects.

Figure 7 Mediator/colleague collection

PKIFv2 provides the MakeDefaultMediator function to create a default collection of mediator and colleague objects which uses Microsoft CAPI for cryptographic support and certificate and CRL storage . PKIFv2 also provides MakeDefaultMediatorNSS to create a default collection of mediator and colleague objects which uses Netscape Security Services for cryptographic support and certificate and CRL storage.These function returns an IPKIFMediatorPtr from which an application can access PKE functionality.

 
Auditing

Additionally, mediators are used to generate audit events. The following events are generated and sent to the Application event log of the host system:

·   Loading and unloading PKIF.dll

·   Exceptions generated by security-critical subcomponents (e.g. colleague objects)

·   Specification of a default signature or decryption key

·   Signature generation failure

·   Signature generation success

·   Signature verification failure

·   Signature verification success

·   Decryption operation success

·   Decryption operation failure

·   Path development failure

·   Path validation failure

·   Path development success

·   Path validation success