com.rsa.certj.provider.revocation.ocsp

Class OCSPResponder

java.lang.Object
  |
  +--com.rsa.certj.provider.revocation.ocsp.OCSPResponder

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

OCSPResponderInternal

public class OCSPResponder

extends Object

implements Cloneable

This class holds information about a particular OCSP responder. Instances of this class are used to configure the behavior of requests and responses processed by the OCSP service provider.

Copyright © RSA Security Inc., 2001. All rights reserved.

Field Summary

static int	FLAG_DISABLE_CERT_SEND Indicates that the service provider should disable sending the signing certificate when the service provider sends signed requests to the responder.
static int	FLAG_DISABLE_NONCES Indicates that the service provider should disable automatic generation and checking of nonces.
static int	FLAG_ENABLE_CHAIN_SEND Indicates that the service provider should enable sending the entire signing certificate chain when the service provider sends signed requests to the responder.
static int	FLAG_RESPONDER_NOCHECK Indicates that the service provider should not check the revocation status of the responder's certificate.
static int	PROFILE_GENERIC Indicates that the responder does not have any vendor-specific behaviors, or that the responder type is unknown.
static int	PROFILE_RSAKCA Indicates that the responder is RSA's KCA (curently v5.7)
static int	PROFILE_VALICERT Indicates that the responder is the ValiCert plug-in for Keon.
static int	PROFILE_VERISIGN Indicates that the responder is VeriSign (OnSite).

Constructor Summary

OCSPResponder(int profile, int flags, String[] destList, String[] proxyList, OCSPRequestControl requestControl, X509Certificate responderCert, X509Certificate[] responderCACerts, DatabaseService database, int tolerance)

Constructs an OCSPResponder object with the full complement of possible initial values.

OCSPResponder(OCSPRequestControl requestControl, X509Certificate[] responderCACerts)

Constructs an OCSPResponder object with contents that are specified only by the CAs of the certificates to check, and a OCSPRequestControl object.

OCSPResponder(OCSPResponder responder)

Constructs an OCSPResponder object with contents that are specified by an existing OCSPResponder object.

Method Summary

Object	clone() Clones this OCSPResponder object.
DatabaseService	getDatabase() Get the database service that is set to store any additional certificates received.
String[]	getDestList() Returns a String array where each element specifies the URL of an OCSP responder.
int	getFlags() Returns an int specifying a collection of bit values used by the service provider to modify how a request should be created or how a response should be interpreted.
int	getProfile() Returns an int value specifying the type of OCSP responder to which the service provider will make requests.
String[]	getProxyList() Returns a String array specifying the URLs of non-transparent proxies of the same protocol that exist between the application and the OCSP responder.
OCSPRequestControl	getRequestControl() Returns an OCSPRequestControl object that controls OCSP request message generation.
X509Certificate[]	getResponderCACerts() Returns an X509Certificate array containing a list of certificates for CAs that use this responder.
X509Certificate	getResponderCert() Returns an X509Certificate object containing the responder's certificate.
int	getTimeTolerance() Gets the time tolerance value for handling clock-skew differences between clients and responders.
void	setDatabase(DatabaseService database) Sets a database service to store any additional certificates received from the responder in the response.
void	setFlags(int flags) Sets a specified flag value.
void	setProfile(int profile) Sets an OCSP profile.
void	setProxyList(String[] proxyList) Sets a list of proxies of this responder.
void	setRequestControl(OCSPRequestControl requestControl) Sets request control information for this responder.
void	setResponderCACerts(X509Certificate[] responderCACerts) Sets the certificates of CA that use this responder.
void	setTimeTolerance(int timeTolerance) Sets the time tolerance value for handling clock-skew differences between clients and responders.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROFILE_GENERIC

public static final int PROFILE_GENERIC

Indicates that the responder does not have any vendor-specific behaviors, or that the responder type is unknown.

PROFILE_VALICERT

public static final int PROFILE_VALICERT

Indicates that the responder is the ValiCert plug-in for Keon.

PROFILE_RSAKCA

public static final int PROFILE_RSAKCA

Indicates that the responder is RSA's KCA (curently v5.7)

PROFILE_VERISIGN

public static final int PROFILE_VERISIGN

Indicates that the responder is VeriSign (OnSite). This profile is not yet officially supported for Releases <= 2.0.1, but may be supported in a future release.

FLAG_DISABLE_NONCES

public static final int FLAG_DISABLE_NONCES

Indicates that the service provider should disable automatic generation and checking of nonces. Use this flag only if you know that the responder being used does not support the checking or generation of nonces, so that the size of the request can be minimized. NOTE: RSA Security does not recommend disabling the use of nonces when they are available. To do so could make OCSP transactions subject to replay attacks.

FLAG_DISABLE_CERT_SEND

public static final int FLAG_DISABLE_CERT_SEND

Indicates that the service provider should disable sending the signing certificate when the service provider sends signed requests to the responder. This flag should not be used when the FLAG_ENABLE_CHAIN_SEND is used, as these flags are contradictory.

FLAG_ENABLE_CHAIN_SEND

public static final int FLAG_ENABLE_CHAIN_SEND

Indicates that the service provider should enable sending the entire signing certificate chain when the service provider sends signed requests to the responder. Any certificates that are required by the responder to verify the request signatures are retrieved from the database field in CertPathCtx when calling CertJ.checkCertRevocation. This flag should not be used when the FLAG_DISABLE_CERT_SEND flag is used, as these flags are contradictory.

FLAG_RESPONDER_NOCHECK

public static final int FLAG_RESPONDER_NOCHECK

Indicates that the service provider should not check the revocation status of the responder's certificate. When this flag is set to true, a clone of the path context is used to validate the response turns off revocation checking for the certificate. If set to false, the status check will be forced to return CertRevocationInfo.CERT_REVOCATION_UNKNOWN when the need arises. This handling is necessary to prevent an OCSP responder from being asked about its own status when OCSP response validation occurs. In particular, when the OCSPResponder.responderCert is not a member of the set of certificates in the CertPathCtx used by checkCertRevocation, a check on the responder's certificate's revocation status will normally be performed. This causes the responder to be asked about its own certificate status, which causes the second response's signer's certificate status to be checked, recursively. It is generally difficult to check the status of an OCSP responder's certificate without a CRL, or by some other out-of- band means and then trusting this certificate in the path context.

Constructor Detail

OCSPResponder

public OCSPResponder(int profile,
                     int flags,
                     String[] destList,
                     String[] proxyList,
                     OCSPRequestControl requestControl,
                     X509Certificate responderCert,
                     X509Certificate[] responderCACerts,
                     DatabaseService database,
                     int tolerance)
              throws InvalidParameterException

Constructs an OCSPResponder object with the full complement of possible initial values.

Parameters

	profile		An int value specifying the type of OCSP responder to which the service provider will make requests. This distinction is required in cases where the service must tailor its behavior to the specified responder. Currently, the possible values are PROFILE_GENERIC, PROFILE_VALICERT, PROFILE_VERISIGN, and PROFILE_XCERT. If the responder type is unknown or no vendor-specific behaviors are required for the service provider to operate correctly, then use PROFILE_GENERIC.
	flags		An int specifying a collection of bit values used by the service provider to modify how a request should be created or how a response should be interpreted. These flags can affect run-time performance and the size of request data. Set it to zero to use the service provider's default set of behaviors. The following is the current set of flags available: FLAG_DISABLE_NONCES FLAG_DISABLE_CERT_SEND FLAG_ENABLE_CHAIN_SEND FLAG_RESPONDER_NOCHECK
	destList		A String array where each element specifies the URL of an OCSP responder. For example, specify a destination URL as follows: http://ocspresp.mycompany.com:181 To specify a locally configured OCSP responder, it must contain only one destination. When the certificate to be checked specifies a responder in its serviceLocator AIA field, it can be used to list one or more URLs.
	proxyList		A String array specifying tje URLs of non-transparent proxies of the same protocol that exist between the application and the OCSP responder. If not specified, this parameter must be set to null. For example, you might specify a proxy URL as follows: http://proxy1.mycompany.com:8080.
	requestControl		An OCSPRequestControl object that controls OCSP request message generation.
	responderCert		An X509Certificate object containing the responder's certificate. The public key contained in this certificate is used to validate response signatures received from the OCSP responder. It can be used to designate a trusted responder that has no affiliation with the trusted chain of the CA that issued the certificate to be validated. This certificate may need to provided in cases where the responder does not include its own certificate in the response data. If specified, this certificate becomes the trusted signer for OCSP responses. If not specified, this parameter should be set to null.
	responderCACerts		An X509Certificate array containing a list of certificates for CAs that use this responder. Responders often service requests on behalf of multiple CAs. Using an array enables a single OCSPResponder to accommodate multiple CA names. It must contain CA certificates that have the same subject name as the issuer name of the certificates to be checked. This parameter is required because the current (1.0) version of the OCSP protocol uses the public key of the issuer's certificate to identify the CA of the certificate being checked, and this information can only be found in its issuer's certificate, and so must be provided here.
	database		A DatabaseService object that is used to store any additional certificates or CRLs that the responder may send back in its responses. If unspecified, this value should be set to null. Additional certificates returned by the provider may be necessary for the service provider to be able to perform certificate-chain validation of signed responses. In these cases, it is necessary that the application bind this database service into the database service handle contained in the CertPathCtx object passed to calls to checkCertRevocation.
	timeTolerance		An int value that specifies how much clock skew to tolerate between the client's and the server's notion of what the current time is. Some CAs return responses that are advertised to be good only from the current time (the time at which the response was issued) forward. This will cause any client whose clock lags the responder's notion of "the current time" to reject the response because the time during which the response it said to be good has not arrived yet, resulting in return status values of CertRevocationInfo.CERT_REVOCATION_UNKNOWN to be generated by the service provider.

Throws

InvalidParameterException - If any argument is invalid.

OCSPResponder

public OCSPResponder(OCSPRequestControl requestControl,
                     X509Certificate[] responderCACerts)
              throws InvalidParameterException

Constructs an OCSPResponder object with contents that are specified only by the CAs of the certificates to check, and a OCSPRequestControl object.

Parameters

	requestControl		An OCSPRequestControl object that controls OCSP request message generation. Set this parameter to null, if it is not specified. It is usually unspecified when it is not necessary to sign requests.
	responderCACerts		An X509Certificate array containing a list of certificates for CAs that use this responder. Responders often service requests on behalf of multiple CAs. Using an array enables a single OCSPResponder to accommodate multiple CA names. It must contain CA certificates that have the same subject name as the issuer name of the certificates to be checked. This parameter is required because the current version (1.0) of the OCSP protocol uses the public key of the issuer's certificate to identify the CA of the certificate to check. This information is only found in its issuer's certificate; therefore, it must be provided here.

Throws

InvalidParameterException - If any argument is invalid.

OCSPResponder

public OCSPResponder(OCSPResponder responder)
              throws InvalidParameterException

Constructs an OCSPResponder object with contents that are specified by an existing OCSPResponder object.

Parameters

responder

An OCSPResponder object to be deep copied.

Throws

InvalidParameterException - If any argument is invalid.

Method Detail

clone

public Object clone()
             throws CloneNotSupportedException

Clones this OCSPResponder object.

Returns

An Object containing the clone.

Throws

CloneNotSupportedException - If an error occurs during the cloning operation.

getProfile

public int getProfile()

Returns an int value specifying the type of OCSP responder to which the service provider will make requests. This distinction is required in cases where the service must tailor its behavior to the specified responder. Currently, the possible values are PROFILE_GENERIC, PROFILE_VALICERT, PROFILE_VERISIGN, and PROFILE_XCERT. If the responder type is unknown or no vendor-specific behaviors are required for the service provider to operate correctly, then use PROFILE_GENERIC.

Returns

An int value specifying the type of OCSP responder to which the service provider will make requests.

getFlags

public int getFlags()

Returns an int specifying a collection of bit values used by the service provider to modify how a request should be created or how a response should be interpreted. These flags can affect run-time performance and the size of request data. Set it to zero to use the service provider's default set of behaviors. The following is the current set of flags available:

      FLAG_DISABLE_NONCES
      FLAG_DISABLE_CERT_SEND
      FLAG_ENABLE_CHAIN_SEND

Returns

An int specifying a collection of bit values used by the service provider to modify how a request should be created or how a response should be interpreted.

getDestList

public String[] getDestList()

Returns a String array where each element specifies the URL of an OCSP responder. For example, specify a destination URL as follows:

http://ocspresp.mycompany.com:181

To specify a locally configured OCSP responder, it must contain only one destination. When the certificate to be checked specifies a responder in its serviceLocator AIA field, it can be used to list one or more URLs.

Returns

A String array where each element specifies the URL of an OCSP responder.

getProxyList

public String[] getProxyList()

Returns a String array specifying the URLs of non-transparent proxies of the same protocol that exist between the application and the OCSP responder. If not specified, this parameter must be set to null. For example, a proxy URL can be specified as follows:

http://proxy1.mycompany.com:8080.

Returns

A String array specifying tje URLs of non-transparent proxies of the same protocol that exist between the application and the OCSP responder.

getRequestControl

public OCSPRequestControl getRequestControl()

Returns an OCSPRequestControl object that controls OCSP request message generation.

Returns

An OCSPRequestControl object that controls OCSP request message generation.

getResponderCert

public X509Certificate getResponderCert()

Returns an X509Certificate object containing the responder's certificate. The public key contained in this certificate is used to validate response signatures received from the OCSP responder. It can be used to designate a trusted responder that has no affiliation with the trusted chain of the CA that issued the certificate to be validated. This certificate may need to provided in cases where the responder does not include its own certificate in the response data. If specified, this certificate identifies the only entity that is to have signed responses from this responder. If not specified, this parameter should be set to null.

Returns

An X509Certificate object containing the responder's certificate.

getResponderCACerts

public X509Certificate[] getResponderCACerts()

Returns an X509Certificate array containing a list of certificates for CAs that use this responder. Responders often service requests on behalf of multiple CAs. Using an array enables a single OCSPResponder to accommodate multiple CA names. It must contain CA certificates that have the same subject name as the issuer name of the certificates to be checked. This parameter is required because the current (RFC 2560) version of the OCSP protocol uses the public key of the issuer's certificate to identify the CA of the certificate being checked, and this information can only be found in its issuer's certificate, and must be provided here.

Returns

An X509Certificate array containing a list of certificates for CAs that use this responder.

setProfile

public void setProfile(int profile)
                throws InvalidParameterException

Sets an OCSP profile.

Parameters

profile

An int value specifying the type of OCSP responder to which the service provider will make requests. This distinction is required in cases where the service must tailor its behavior to the specified responder. Currently, the possible values are PROFILE_GENERIC, PROFILE_VALICERT, PROFILE_VERISIGN, and PROFILE_XCERT. If the responder type is unknown or no vendor-specific behaviors are required for the service provider to operate correctly, then use PROFILE_GENERIC.

Throws

InvalidParameterException - If the argument is invalid.

setFlags

public void setFlags(int flags)
              throws InvalidParameterException

Sets a specified flag value.

Parameters

flags

An int specifying a collection of bit values used by the service provider to modify how a request should be created or how a response should be interpreted. These flags can affect run-time performance and the size of request data. Set it to zero to use the service provider's default set of behaviors. The following is the current set of available flags: FLAG_DISABLE_NONCES FLAG_DISABLE_CERT_SEND FLAG_ENABLE_CHAIN_SEND

Throws

InvalidParameterException - If the argument is invalid.

setProxyList

public void setProxyList(String[] proxyList)
                  throws InvalidParameterException

Sets a list of proxies of this responder.

Parameters

proxyList

A String array specifying URLs of proxies of the same protocol that exists between the application and the OCSP auto-responder. For example, a proxy URL can be specified as follows: http://proxy1.mycompany.com:8080

Throws

InvalidParameterException - If the argument is invalid.

setRequestControl

public void setRequestControl(OCSPRequestControl requestControl)
                       throws InvalidParameterException

Sets request control information for this responder.

Parameters

requestControl

An OCSPRequestControl object that controls OCSP request message generation.

Throws

InvalidParameterException - If the argument is invalid.

setResponderCACerts

public void setResponderCACerts(X509Certificate[] responderCACerts)
                         throws InvalidParameterException

Sets the certificates of CA that use this responder.

Parameters

responderCACerts

An X509Certificate array containing a list of certificates for CAs that use this responder. Responders often service requests on behalf of multiple CAs. Using an array enables a single OCSPResponder to accommodate multiple CA names. It must contain CA certificates that have the same subject name as the issuer name of the certificates to be checked.

Throws

InvalidParameterException - If the argument is invalid.

setDatabase

public void setDatabase(DatabaseService database)
                 throws InvalidParameterException

Sets a database service to store any additional certificates received from the responder in the response.

Parameters

database

A DatabaseService object that is used to store any additional that the responder may send back in its responses. These additional certificates are generally used to assist the requester in building a certificate chain for response signature verification. The application should also bind a component service provider of this database service to the database service of the CertPathCtx object passed to calls to either CertJ.verifyCertPath, or CertJ.buildCertPath as the database service provider may contain intermediate certificates needed to verify or build a valid certification path. If no such database instances are required, set this value to null.

Throws

InvalidParameterException - If the argument is invalid.

getDatabase

public DatabaseService getDatabase()

Get the database service that is set to store any additional certificates received.

Returns

The DatabaseService into which any additional certificates received from the responder are stored.

setTimeTolerance

public void setTimeTolerance(int timeTolerance)

Sets the time tolerance value for handling clock-skew differences between clients and responders. The validity period of the response is extended both into the future and into the past by the specified amount of time. For example, if an OCSP responder states that the validity period of the response that it is providing is only good from the time it creates it response through five minutes into the future, and either the client's clock is behind that of the server, or more than five minutes ahead into the future, the status check response will be rejected by the service provider. By specifying a non-zero value for timeTolerance, this amount of tolerance is applied to validity windows that are very narrow and sensitive to clock differences between the client and the server.

Parameters

timeTolerance

An int specifying the number of seconds that the OCSP responder should extend the validity period of the response, both into the future and into the past.

getTimeTolerance

public int getTimeTolerance()

Gets the time tolerance value for handling clock-skew differences between clients and responders.

Returns

An int specifying the number of seconds that the OCSP responder should extend the validity period of the response, both into the future and into the past.