CPKIFOCSPChecker Class Reference

#include <PKIFOCSPChecker.h>

Inheritance diagram for CPKIFOCSPChecker:

Inheritance graph
[legend]
Collaboration diagram for CPKIFOCSPChecker:

Collaboration graph
[legend]

List of all members.

Detailed Description

The CPKIFOCSPChecker class is the primary means by which applications obtain OCSP functionality, albeit indirectly. This class serves as a revocation status colleague and may be configured to contact a local, trusted OCSP responder or to contact OCSP responders identified by AIA extensions. All interaction with OCSP responders is via HTTP. See the sample Enabling OCSP.

The MakeDefaultMediator function includes an instance of this class in the default mediator/colleague collection to service AIA-specified OCSP responders. Applications can add an instance to interact with a trusted OCSP responder, e.g. a responder trusted to provide appropriate response for any OCSP query, by creating an instance of this class, specifying the hostname and port then passing the instance to MakeDefaultMediator.

TSP-enforcing: Yes

Definition at line 41 of file PKIFOCSPChecker.h.


Public Member Functions

 CPKIFOCSPChecker (void)
virtual ~CPKIFOCSPChecker (void)
 CPKIFOCSPChecker (const CPKIFOCSPChecker &copy)
void SetHost (const char *host)
void Set_Port (int port)
void SetURL (const char *url)
CPKIFStringPtr GetHost () const
CPKIFStringPtr GetURL () const
int GetPort () const
void SetMultiCertRequest (bool bDoMultiCertRequests)
bool GetMultiCertRequest ()
void Initialize ()
bool CheckStatus (const CPKIFCertificatePtr &targetCert, const CPKIFCertificatePtr &issuersCert, RevocationStatus &status, CPKIFCertStatusPtr &certStatus)
bool CheckStatusPath (CPKIFCertificatePath &path, RevocationStatus &status)
void SetPathSettings (CPKIFPathSettingsPtr &settings)
void SetSigningCredential (CPKIFCredentialPtr &cred)
CPKIFCredentialPtr GetSigningCredential () const
void SetResponderPublicKey (CPKIFCertificatePtr &cert, bool bRequireThisCert=false)
CPKIFCertificatePtr GetResponderPublicKey () const
bool GetRequireSpecificCert () const
void AddNamespace (CPKIFGeneralSubtreePtr &name)
CPKIFGeneralSubtreeList GetNamespaces ()
void AddIssuerNamespace (CPKIFGeneralSubtreePtr &name)
CPKIFGeneralSubtreeList GetIssuerNamespaces ()
void SetGenerateNonce (bool bGenerateNonce)
bool GetGenerateNonce ()
void SetRequireNonceMatch (bool bRequireNonceMatch)
bool GetRequireNonceMatch ()
bool ProcessOfflineResponse (CPKIFCertificatePtr &targetCert, CPKIFCertificatePtr &targetIssuer, bool responderIsTrusted, CPKIFBufferPtr &ocspResponse, CPKIFCertStatusPtr &targetCertStatus)
void SetCacheValidatedResponders (bool b)
bool GetCacheValidatedResponders ()

Friends

struct CPKIFOCSPCheckerImpl

Constructor & Destructor Documentation

CPKIFOCSPChecker::CPKIFOCSPChecker ( void   ) 

Interface: External

This function creates CPKIFOCSPChecker objects. Prior to use by a CPKIFRevocationStatusMediator2, the Initialize function must be called. This function initializes the following properties to the indicated values: 



    

  • Port: 80
  • GenerateNonce: false
  • RequireNonceMatch: true






Returns:
None 



Definition at line 2168 of file CACOCSPChecker.cpp.



References LOG_STRING_DEBUG, and TOOLKIT_OCSP_CHECKER.



Referenced by MakeOCSPChecker().











      

        

          CPKIFOCSPChecker::~CPKIFOCSPChecker           
          (
          void 
                    
           ) 
           [virtual]
        

      








Interface: External

This function destroys CPKIFOCSPChecker objects.


Returns:
None 



Definition at line 2256 of file CACOCSPChecker.cpp.



References LOG_STRING_DEBUG, and TOOLKIT_OCSP_CHECKER.











      

        

          CPKIFOCSPChecker::CPKIFOCSPChecker           
          (
          const CPKIFOCSPChecker & 
           copy          
           ) 
          
        

      








Interface: External

Copy constructor for CPKIFOCSPChecker class


Returns:
None 


Parameters: 




copy 
[in] A reference toCPKIFOCSPChecker object which will be duplicated 






Definition at line 2199 of file CACOCSPChecker.cpp.



References m_impl.







Member Function Documentation






      

        

          void CPKIFOCSPChecker::SetHost           
          (
          const char * 
           host          
           ) 
          
        

      








Interface: External

This function is used to specify the hostname of a local, trusted OCSP responder. The name should be expressed as an IP address or DNS name. Once a host has been specified, the instance of CPKIFOCSPChecker is configured to operate assuming the responder is trusted as a source of status information for all certificates. An instance of CPKIFOCSPChecker can not be changed from operating as a client for a local, trusted responder to operate as a client for potentially untrusted responders. Specification of an unreachable host will not manifest itself as an error until an attempt is made to contact the responder.

Passing NULL as the host parameter will result in a CPKIFOCSPException indicating COMMON_INVALID_INPUT.


Returns:
None


Exceptions:

  

    
CPKIFOCSPException(COMMON_INVALID_INPUT) 

  




Parameters: 




host 
[in] Pointer to a NULL-terminated string identifying the hostname of an OCSP responder 






Definition at line 2291 of file CACOCSPChecker.cpp.



References COMMON_INVALID_INPUT.











      

        

          void CPKIFOCSPChecker::Set_Port           
          (
          int 
           port          
           ) 
          
        

      








Interface: External

This function is used to specify the port used by the OCSP responder identified by the hostname parameter. The default value for the port parameter is 80.

Specification of a port value greater than 65535 will result in a CPKIFOCSPException indicating COMMON_INVALID_INPUT.


Returns:
None


Exceptions:

  

    
CPKIFOCSPException(COMMON_INVALID_INPUT) 

  




Parameters: 




port 
[in] Integer identifying the port used to communicate with the OCSP responder identified by the hostname parameter 






Definition at line 2356 of file CACOCSPChecker.cpp.



References COMMON_INVALID_INPUT.











      

        

          void CPKIFOCSPChecker::SetURL           
          (
          const char * 
           url          
           ) 
          
        

      








Interface: External

This function is used to specify the URL of a local, trusted OCSP responder. Once a URL has been specified, the instance of CPKIFOCSPChecker is configured to operate assuming the responder is trusted as a source of status information for all certificates. Specifying a URL will invalidate any host that was previously specified. An instance of CPKIFOCSPChecker can not be changed from operating as a client for a local, trusted responder to operate as a client for potentially untrusted responders. Specification of an invalid URL will not manifest itself as an error until an attempt is made to contact the responder.

Passing NULL as the host parameter will result in a CPKIFOCSPException indicating COMMON_INVALID_INPUT.


Returns:
None


Exceptions:

  

    
CPKIFOCSPException(COMMON_INVALID_INPUT) 

  




Parameters: 




url 
[in] Pointer to a NULL-terminated string identifying the URL of an OCSP responder 






Definition at line 2326 of file CACOCSPChecker.cpp.



References COMMON_INVALID_INPUT.











      

        

          CPKIFStringPtr CPKIFOCSPChecker::GetHost           
          (
                    
           ) 
           const
        

      








Interface: External

This function returns a reference counted smart pointer to a string representing the host name or NULL. If non-NULL, then this instance is associated with a locally trusted responder.


Returns:
None 



Definition at line 2730 of file CACOCSPChecker.cpp.











      

        

          CPKIFStringPtr CPKIFOCSPChecker::GetURL           
          (
                    
           ) 
           const
        

      








Interface: External

This function returns a reference counted smart pointer to a string representing the URL or NULL. If non-NULL, then this instance is associated with a locally trusted responder.


Returns:
None 



Definition at line 2743 of file CACOCSPChecker.cpp.











      

        

          int CPKIFOCSPChecker::GetPort           
          (
                    
           ) 
           const
        

      








Interface: External

This function returns the port associated with this instance. The port is only used if the host name property is non-NULL.


Returns:
None 



Definition at line 2755 of file CACOCSPChecker.cpp.











      

        

          void CPKIFOCSPChecker::SetMultiCertRequest           
          (
          bool 
           bDoMultiCertRequests          
           ) 
          
        

      








Interface: External

This function is used to control whether requests generated by a particular instance of CPKIFOCSPChecker may generate requests containing multiple certificates.


Returns:
N/A 


Parameters: 




bDoMultiCertRequests 
[in] Boolean value that indicates whether requests may contain multiple certificates 






Definition at line 2865 of file CACOCSPChecker.cpp.











      

        

          bool CPKIFOCSPChecker::GetMultiCertRequest           
          (
                    
           ) 
          
        

      








Interface: External

This function returns a boolean value that indicates whether requests generated by a particular instance of CPKIFOCSPChecker may generate requests containing multiple certificates.


Returns:
N/A 



Definition at line 2880 of file CACOCSPChecker.cpp.











      

        

          void CPKIFOCSPChecker::Initialize           
          (
          void 
                    
           ) 
           [virtual]
        

      








Interface: External

This function initializes an instance for use in a collection of IPKIFColleague objects held by a mediator.


Returns:
None 



Reimplemented from IPKIFColleague.



Definition at line 2270 of file CACOCSPChecker.cpp.



References LOG_STRING_DEBUG, and TOOLKIT_OCSP_CHECKER.











      

        

          bool CPKIFOCSPChecker::CheckStatus           
          (
          const CPKIFCertificatePtr & 
           targetCert, 
        

        

          
          
          const CPKIFCertificatePtr & 
           issuersCert, 
        

        

          
          
          RevocationStatus & 
           status, 
        

        

          
          
          CPKIFCertStatusPtr & 
           certStatus 
        

        

          
          )
           [virtual]
        

      








Interface: External

This function may be used to check the revocation status of a single certificate. It is not typically invoked directly by applications. Instead, applications invoke this function on a mediator object with which an instance of this class has been associated.


Returns:
This function returns true if the revocation status could be determined and false otherwise


Exceptions:

  

    
CPKIFException(COMMON_MEDIATOR_MISSING) 

    
CPKIFException(COMMON_INVALID_INPUT) 

  




Parameters: 




targetCert 
[in] Reference to a smart pointer to a CPKIFCertificate object containing the certificate for which revocation status is sought 


issuersCert 
[in] Reference to a smart pointer to a CPKIFCertificate object containing the certificate of the issuer of the certificate passed via the cert parameter 


status 
[out] Reference to a RevocationStatus variable to receive the revocation status 


certStatus 
[out] Reference to a smart pointer to a CPKIFCertStatus object containing status information about target certificate 






Implements IPKIFRevocationStatus.



Definition at line 2382 of file CACOCSPChecker.cpp.



References COMMON_INVALID_INPUT, COMMON_MEDIATOR_MISSING, g_adOCSP, g_ocspNoCheck, LOG_STRING_DEBUG, NOT_CHECKED, NOT_REVOKED, and TOOLKIT_OCSP_CHECKER.











      

        

          bool CPKIFOCSPChecker::CheckStatusPath           
          (
          CPKIFCertificatePath & 
           path, 
        

        

          
          
          RevocationStatus & 
           status 
        

        

          
          )
           [virtual]
        

      








Interface: External

This function is used to check the revocation status of each certificate in a certification path. It is invoked during path validation to determine the revocation status of each certificate in a certificate pa.


Returns:
This function returns true if the revocation status could be determined and false otherwise.


Exceptions:

  

    
CPKIFException(COMMON_MEDIATOR_MISSING) 

  




Parameters: 




path 
[in/out] Reference to a CPKIFCertificatePath object containing the certificates for which revocation status is 


status 
[out] Reference to a RevocationStatus object to receive the least successful revocation status value assigned to a certificate passed via the path parameter 






Implements IPKIFRevocationStatus.



Definition at line 2492 of file CACOCSPChecker.cpp.



References COMMON_INVALID_INPUT, COMMON_MEDIATOR_MISSING, g_adOCSP, g_ocspNoCheck, CPKIFCertificate::GetExtensionByOID(), CPKIFCertificatePath::GetPath(), CPKIFCertificatePath::GetPathSettings(), CPKIFCertificatePath::GetTarget(), CPKIFCertificatePath::GetTrustRoot(), LOG_STRING_DEBUG, NOT_CHECKED, NOT_REVOKED, and TOOLKIT_OCSP_CHECKER.











      

        

          void CPKIFOCSPChecker::SetPathSettings           
          (
          CPKIFPathSettingsPtr & 
           settings          
           ) 
          
        

      








Interface: External

This function are used to set and retrieve the initial path settings used by path development and validation operations.


Returns:
None 


Parameters: 




settings 
[in/out] Reference to a smart pointer to a CPKIFPathSettings object 






Definition at line 1237 of file CACOCSPChecker.cpp.











      

        

          void CPKIFOCSPChecker::SetSigningCredential           
          (
          CPKIFCredentialPtr & 
           cred          
           ) 
          
        

      








Interface: External

This function enables user to specify credentials that will be used to sign the OCSP request.


Returns:
None 


Parameters: 




cred 
[in] A reference to a smart pointer which contains the credentials that will be used to sign the OCSP request. 






Definition at line 2694 of file CACOCSPChecker.cpp.











      

        

          CPKIFCredentialPtr CPKIFOCSPChecker::GetSigningCredential           
          (
                    
           ) 
           const
        

      








Interface: External

This function returns the signing credentials associated with this instance.


Returns:
A smart pointer to the signing credentials associated with this instance 



Definition at line 2766 of file CACOCSPChecker.cpp.











      

        

          void CPKIFOCSPChecker::SetResponderPublicKey           
          (
          CPKIFCertificatePtr & 
           cert, 
        

        

          
          
          bool 
           bRequireThisCert = false 
        

        

          
          )
          
        

      








Interface: External

This function enables user to a public key, or specific certificate, for a local OCSP responder. This field is not used when processing responses from responders located using an AIA extension. The cert parameter contains the public key that must be used to verify the signature. If bRequireThisCert is set to true then the exact certificate must be used.


Returns:
None 


Parameters: 




cert 
A reference to a smart pointer which contains a certificate that contains the public key used to verify responses 


bRequireThisCert 
Boolean indicating whether the public key and name must match (false) or the certificate must match (true) 






Definition at line 2711 of file CACOCSPChecker.cpp.











      

        

          CPKIFCertificatePtr CPKIFOCSPChecker::GetResponderPublicKey           
          (
                    
           ) 
           const
        

      








Interface: External

This function returns responders public key associated with this instance.


Returns:
A smart pointer to the responders certificate associated with this instance 



Definition at line 2777 of file CACOCSPChecker.cpp.











      

        

          bool CPKIFOCSPChecker::GetRequireSpecificCert           
          (
                    
           ) 
           const
        

      








Interface: External

This function returns specific certificate required by this instance.


Returns:
A smart pointer to the specific certificate required by this instance 



Definition at line 2788 of file CACOCSPChecker.cpp.











      

        

          void CPKIFOCSPChecker::AddNamespace           
          (
          CPKIFGeneralSubtreePtr & 
           name          
           ) 
          
        

      








Interface: External

This function adds a namespace to an OCSP checker instance. Requests will be generated for certificates containing a subject name that falls within a namespace passed to this function. The function returns without taking any action if the name parameter is NULL.


Returns:
N/A 


Parameters: 




name 
[in] Pointer to a CPKIFGeneralSubtree object containing the name to add 






Definition at line 2803 of file CACOCSPChecker.cpp.











      

        

          CPKIFGeneralSubtreeList CPKIFOCSPChecker::GetNamespaces           
          (
                    
           ) 
          
        

      








Interface: External

This function returns a vector containing the CPKIFGeneralSubtree objects passed to the AddNamespace function.


Returns:
possibly empty vector of CPKIFGeneralSubtreePtr objects 



Definition at line 2820 of file CACOCSPChecker.cpp.











      

        

          void CPKIFOCSPChecker::AddIssuerNamespace           
          (
          CPKIFGeneralSubtreePtr & 
           name          
           ) 
          
        

      








Interface: External

This function adds a issuer namespace to an OCSP checker instance. Requests will be generated for certificates containing a issuer name that falls within a namespace passed to this function. The function returns without taking any action if the name parameter is NULL.


Returns:
N/A 


Parameters: 




name 
[in] Pointer to a CPKIFGeneralSubtree object containing the name to add 






Definition at line 2835 of file CACOCSPChecker.cpp.











      

        

          CPKIFGeneralSubtreeList CPKIFOCSPChecker::GetIssuerNamespaces           
          (
                    
           ) 
          
        

      








Interface: External

This function returns a vector containing the CPKIFGeneralSubtree objects passed to the AddIssuerNamespace function.


Returns:
possibly empty vector of CPKIFGeneralSubtreePtr objects 



Definition at line 2852 of file CACOCSPChecker.cpp.











      

        

          void CPKIFOCSPChecker::SetGenerateNonce           
          (
          bool 
           bGenerateNonce          
           ) 
          
        

      








Interface: External

This function is used to retrieve the indicator whether a nonce should be generated or not.


Returns:
None 


Parameters: 




bGenerateNonce 
[in] Boolean value which indicates whether a nonce should be generated or not. 






Definition at line 1252 of file CACOCSPChecker.cpp.











      

        

          bool CPKIFOCSPChecker::GetGenerateNonce           
          (
                    
           ) 
          
        

      








Interface: External

This function is used to retrieve the indicator whether a nonce should be generated or not.


Returns:
A boolean ndicator whether a nonce should be generated or not 



Definition at line 1265 of file CACOCSPChecker.cpp.











      

        

          void CPKIFOCSPChecker::SetRequireNonceMatch           
          (
          bool 
           bRequireNonceMatch          
           ) 
          
        

      








Interface: External

This function is used to set the indicator whether a nonce should match or not.


Returns:
None 


Parameters: 




bRequireNonceMatch 
[in] Boolean value which indicates whether a nonce should match or not. 






Definition at line 1276 of file CACOCSPChecker.cpp.











      

        

          bool CPKIFOCSPChecker::GetRequireNonceMatch           
          (
                    
           ) 
          
        

      








Interface: External

This function is used to retrieve the indicator whether a nonce should match or not.


Returns:
A boolean indicator whether a nonce should match or not 



Definition at line 1289 of file CACOCSPChecker.cpp.











      

        

          bool CPKIFOCSPChecker::ProcessOfflineResponse           
          (
          CPKIFCertificatePtr & 
           targetCert, 
        

        

          
          
          CPKIFCertificatePtr & 
           targetCertIssuer, 
        

        

          
          
          bool 
           responderIsTrusted, 
        

        

          
          
          CPKIFBufferPtr & 
           ocspResponse, 
        

        

          
          
          CPKIFCertStatusPtr & 
           targetCertStatus 
        

        

          
          )
          
        

      








Interface: External

This function can be used to process an OCSP response that was previously retrieved (possibly by another entity), e.g. an OCSP response that delivered as part of a protocol message. This function may generate an exception containing one of the following error codes OCSP_UNPROCESSED_CRITICAL_EXTENSION, PATH_CERT_REVOKED and PATH_CERT_REVOCATION_STATUS_NOT_DETERMINED.


Returns:
None


Exceptions:

  

    
OCSP_UNPROCESSED_CRITICAL_EXTENSION 

    
PATH_CERT_REVOKED 

    
PATH_CERT_REVOCATION_STATUS_NOT_DETERMINED 

  




Parameters: 




targetCert 
[in] Reference to a smart pointer to a CPKIFCertificate object containing the certificate for which revocation status is sought 


targetCertIssuer 
[in] Reference to a smart pointer to a CPKIFCertificate object containing the certificate of the issuer of targetCert 


responderIsTrusted 
[in] Boolean indicating whether the OCSP responder is trusted to provide status for any certificate 


ocspResponse 
[in] Reference to a smart pointer to a CPKIFBuffer object containing the OCSP response that presumable contains status information related to the target certificate 


targetCertStatus 
[out] Reference to a smart pointer to a CPKIFCertStatus object to receive the status information 






Definition at line 1642 of file CACOCSPChecker.cpp.



References g_ocspNonce, LOG_STRING_DEBUG, NOT_CHECKED, OCSP_UNPROCESSED_CRITICAL_EXTENSION, PATH_CERT_REVOCATION_STATUS_NOT_DETERMINED, PATH_CERT_REVOKED, REV_INFO_CAST, REVOKED, REVSOURCE_OCSP, and TOOLKIT_OCSP_CHECKER.











      

        

          void CPKIFOCSPChecker::SetCacheValidatedResponders           
          (
          bool 
           b          
           ) 
          
        

      








Interface: External

This function sets if the validated responders will be cached


Returns:
None 


Parameters: 




b 
[out] True if validated responders will be cached, false otherwise 






Definition at line 287 of file CACOCSPChecker.cpp.











      

        

          bool CPKIFOCSPChecker::GetCacheValidatedResponders           
          (
                    
           ) 
          
        

      








Interface: External

This function indicates if the validated responders will be cached


Returns:
True if validated responders will be cached, false otherwise 



Definition at line 300 of file CACOCSPChecker.cpp.







Friends And Related Function Documentation






      

        

          friend struct CPKIFOCSPCheckerImpl [friend]          
        

      










Definition at line 43 of file PKIFOCSPChecker.h.







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



Generated on Mon Nov 15 11:20:30 2010 for PublicKeyInfrastructureFramework(PKIF) by 

doxygen 1.5.6