com.entrust.toolkit.x509

Class UserRevocationInfo

java.lang.Object

com.entrust.toolkit.x509.UserRevocationInfo

public class UserRevocationInfo
extends java.lang.Object

This class maintains an ordered list of revocation information which is used to configure the underlying RevocationManager. Information can be stored in a properties file or configured through this object.

Revocation is performed by the RevocationChecker objects, which can consist of the following:

• A single RevocationTrustCache RevocationChecker - used to speed up revocation checking. If enabled, this checker is always placed first in the order of revocation checkers. By default it is not enabled.
• A single CollectionRS Revocation Checker. Used for CRL verification
• Any number of OCSPRevocationChecker objects. Multiple OCSP responders can be configured for revocation.
• Any number of MultiOCSPLocalRevocationChecker - objects which are used to group one or more OCSPRevocationCheckers mapped by the CADN

The order of these Revocation Checkers is important, as revocation information will be searched in the specified order.

If the RevocationTrustCache is enabled, it will always be checked first.

To configure the order of revocation two methods can be employed:

1. The API's in this class can be used to setup the order of Revocation using the addRevocationConfigItem(RevocationConfigItem) method. The RevocationConfigItem is an object which wraps the type of configuration (CRL, OCSP, OCSPGroup} to the type of data being stored. The trustcache is enabled or disabled by calling the setTrustCacheInterval(int). In most cases, it should be desirable to use the convienance methods addCRLRevocationChecking(boolean), addOCSPConfiguration(OCSPConfiguration), addOCSPGroup(OCSPConfiguration[]), and setTrustCacheInterval(int).

2. This class contains method parsePropertiesFile(InputStream) to read in a java properties file containing revocation configuration information. If this method is used to configure revocation, any existing configuration in the current class will be overwritten. This class also contains a method writePropertiesFile(OutputStream, String) which allows you to write the current revocation configuration stored in this class to a java properties file which can be later read by the parsePropertiesFile(InputStream).

Note: The RevocationTrustCache can only be enabled using the API setTrustCacheInterval(int).

For example, if reading in from a Java properties file, the following code could be used to setup revocation information:

 UserRevocationInfo revinfo = new UserRevocationInfo();
 revinfo.parsePropertiesFile("C:/Development/JavaTK/OCSP/ocspconfig.properties");
 revinfo.setTrustCacheInterval(3600) // Set Trust cache to 1 hour
 
 UserConfigSettings usersettings = new UserConfigSettings();
 usersettings.setRevocationInfo(revinfo);
 
 User user = new User(usersettings);
 user.login(credentialReader, securePassword);
 .
 . //Rest of program here...
 . 
 

For information on the format of the configuration file, see methods parsePropertiesFile(InputStream) and writePropertiesFile(OutputStream, String)

Since:

7.2

See Also:

RevocationTrustCache, OCSPRevocationChecker, MultiOCSPLocalRevocationChecker, CollectionRS, RevocationManager, RevocationChecker

Constructor Summary

Constructors

Constructor and Description
UserRevocationInfo() The default constructor for UserRevocationInfo
UserRevocationInfo(KeyAndCertContainer user) The default constructor for UserRevocationInfo

Method Summary

Modifier and Type	Method and Description
void	addCRLRevocationChecking(boolean requireCRL) Convienance method for adding a CRL revocation into the list of Revocaton configurations.
void	addCRLRevocationChecking(boolean requireCRL, int position) Convienance method for adding a CRL revocation into the list of Revocation configurations at the desired position.
void	addCRLRevocationChecking(CRLConfig config) Add a CRLConfig using a CRLConfig object that carries the CRL configuration information
void	addOCSPConfiguration(OCSPConfiguration OCSPConfig) Convienance method for adding OCSP revocation into the list of Revocaton configurations.
void	addOCSPConfiguration(OCSPConfiguration OCSPConfig, int position) Convienance method for adding an OCSP revocation into the list of Revocation configurations at the desired position.
void	addOCSPGroup(OCSPConfiguration[] configs) Convienance method for adding a Group of OCSP configurations into the list of Revocation configurations.
void	addOCSPGroup(OCSPConfiguration[] configs, int position) Convienance method for adding a Group of OCSP configurations into the list of Revocation configurations at the desired position.
void	addRevocationConfigItem(RevocationConfigItem revocationconfig) Adds a revocation configuration item to the end of the list of revocation configurations.
void	addRevocationConfigItem(RevocationConfigItem config, int position) Adds a new revocation configuration, at the specified position.
RevocationConfigItem[]	getRevocationConfigList() Returns an array of RevocationConfigItem which represents the current order of revocation information which has been configured by this class.
int	getTrustCacheInterval() Returns the number of seconds the Trust Cache is valid.
void	parsePropertiesFile(java.io.InputStream file) Parses a revocation configuration based on a properties file and maps it into the specified revocation order.
RevocationConfigItem	removeRevocationConfiguration(int index) Removes a RevocationConfiguration using the given index from the list of RevocationConfigurations.
void	setKeyAndCertContainer(KeyAndCertContainer info) Sets the key and certificate container object which is required for OCSP request signing.
void	setTrustCacheInterval(int seconds) To enable the Revocation Trust Cache, a value greater than 0 should be set.
void	writePropertiesFile(java.io.OutputStream filename, java.lang.String certLocation) Write the current Revocation Configuration which this class represents to the specified OutputStream.

Methods inherited from class java.lang.Object

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

Constructor Detail

UserRevocationInfo

public UserRevocationInfo()

The default constructor for UserRevocationInfo

UserRevocationInfo

public UserRevocationInfo(KeyAndCertContainer user)

The default constructor for UserRevocationInfo

Method Detail

setTrustCacheInterval

public void setTrustCacheInterval(int seconds)

To enable the Revocation Trust Cache, a value greater than 0 should be set. If seconds is less than 1, then the trust cache will be disabled. The Maximum value of the Trust Cache is 86400 seconds (24 hours).

When the revocation trust cache is enabled, the revocation status of the certificate in question is not re-checked unless it has been in the cache for longer than the number of seconds specified by this setting.

Parameters:

seconds - The number of seconds revocation is valid. If seconds < 0 then seconds will be set to 0. If seconds is > 86400 then seconds will be set to 86400.

getTrustCacheInterval

public int getTrustCacheInterval()

Returns the number of seconds the Trust Cache is valid. If a value of less than 1 is returned, then the Trust Cache is disabled.

addRevocationConfigItem

public void addRevocationConfigItem(RevocationConfigItem config,
                                    int position)

Adds a new revocation configuration, at the specified position. The position is the preference order in which revocation is checked. If an item already exists in the list, then it will not be added. If the specified position is out of bounds, the item will be added to the end of the list.

Parameters:

config - the RevocationConfigItem to add

position - the Position in which the RevocationConfigItem should be added.

addRevocationConfigItem

public void addRevocationConfigItem(RevocationConfigItem revocationconfig)

Adds a revocation configuration item to the end of the list of revocation configurations. If the RevocationConfigItem does not exist in the list, it will be added. If an item already exists in the list, then it will not be added.

Parameters:

revocationconfig - The revocation configuration

addCRLRevocationChecking

public void addCRLRevocationChecking(boolean requireCRL)

Convienance method for adding a CRL revocation into the list of Revocaton configurations. It is equivalent to calling:

 RevocationConfigItem CRLChecking = new RevocationConfigItem(UserRevocationInfo.CRL, null);
 addRevocationConfigItem(CRLChecking, position);
 

Parameters:

requireCRL - set to true if a CRL is required for CRL verification, false if it is not required.

addCRLRevocationChecking

public void addCRLRevocationChecking(CRLConfig config)

Add a CRLConfig using a CRLConfig object that carries the CRL configuration information

Parameters:

config - the CRLConfig object carrying the CRL configuration information

addCRLRevocationChecking

public void addCRLRevocationChecking(boolean requireCRL,
                                     int position)

Convienance method for adding a CRL revocation into the list of Revocation configurations at the desired position. It is equivalent to calling:

 RevocationConfigItem CRLChecking = new RevocationConfigItem(UserRevocationInfo.CRL, null);
 addRevocationConfigItem(CRLChecking, position);
 

Only one CRLRevocation Checker can be specified.

Parameters:

position - the Position in the list of revocation configurations where CRL revocation checking should be done. If given position is outside the bounds of revocation configurations, it will be added to the end of the List of revocation configurations.

getRevocationConfigList

public RevocationConfigItem[] getRevocationConfigList()

Returns an array of RevocationConfigItem which represents the current order of revocation information which has been configured by this class.

Returns:

array of RevocationConfigItem

removeRevocationConfiguration

public RevocationConfigItem removeRevocationConfiguration(int index)

Removes a RevocationConfiguration using the given index from the list of RevocationConfigurations. If the specified index is out of range, nothing will be removed.

Parameters:

index - The index at which the Revocation Configuration should be removed

Returns:

the RevocationConfigItem that was removed, or null if nothing was removed.

addOCSPConfiguration

public void addOCSPConfiguration(OCSPConfiguration OCSPConfig)

Convienance method for adding OCSP revocation into the list of Revocaton configurations. It is equivalent to calling:

 RevocationConfigItem OCSPChecking = new RevocationConfigItem(UserRevocationInfo.OCSP,OCSPConfig);
 addRevocationConfigItem(OCSPChecking);
 

Any number of OCSPConfigurations can be used. If this specific OCSPConfiguration has already been added to the list, it will not be added again.

Parameters:

OCSPConfig - The OCSPConfiguration

addOCSPConfiguration

public void addOCSPConfiguration(OCSPConfiguration OCSPConfig,
                                 int position)

Convienance method for adding an OCSP revocation into the list of Revocation configurations at the desired position. It is equivalent to calling:

 RevocationConfigItem OCSPChecking = new RevocationConfigItem(UserRevocationInfo.OCSP,OCSPConfig);
 addRevocationConfigItem(OCSPChecking,position);
 

Any number of OCSPConfigurations can be used. If this specific OCSPConfiguration has already been added to the list, it will not be added again.

Parameters:

OCSPConfig - The OCSPConfiguration

position - the Position in the list of revocation configurations where OCSP revocation checking should be done. If given position is outside the bounds of revocation configurations, it will be added to the end of the List of revocation configurations.

addOCSPGroup

public void addOCSPGroup(OCSPConfiguration[] configs)

Convienance method for adding a Group of OCSP configurations into the list of Revocation configurations. It is equivalent to calling:

 RevocationConfigItem OCSPGroup = new RevocationConfigItem(UserRevocationInfo.OCSPGROUP,configs);
 addRevocationConfigItem(OCSPGroup);    
 

This method allows multiple ocsp configurations to be grouped together for more efficient processing of OCSP requests.

This configuration will use a MultiOCSPLocalRevocationChecker object which maps Issuer Names (CADN's) to locally configured responders. The Issuer names will be retrieved from the supplied OCSPConfigurations. If the OCSPConfiguration does not contain any configured CADN's then this locally configured responder will be considered a "default" responder, and can be used to send all OCSP requests.

Note: Using this method will not add any benefit unless there is more than one locally configured responder.

Parameters:

configs - An array of OCSPConfigurations

addOCSPGroup

public void addOCSPGroup(OCSPConfiguration[] configs,
                         int position)

Convienance method for adding a Group of OCSP configurations into the list of Revocation configurations at the desired position. It is equivalent to calling:

 RevocationConfigItem OCSPGroup = new RevocationConfigItem(UserRevocationInfo.OCSPGROUP,configs);
 addRevocationConfigItem(OCSPGroup);    
 

This method allows multiple ocsp configurations to be grouped together for more efficient processing of OCSP requests.

This configuration will use a MultiOCSPLocalRevocationChecker object which maps Issuer Names (CADN's) to locally configured responders. The Issuer names will be retrieved from the supplied OCSPConfigurations. If the OCSPConfiguration does not contain any configured CADN's then this locally configured responder will be considered a "default" responder, and can be used to send all OCSP requests.

Note: Using this method will not add any benefit unless there is more than one locally configured responder.

Parameters:

configs - An array of OCSPConfigurations

position - the Position in the list of revocation configurations where this group of OCSP revocation checkers should be added. If given position is outside the bounds of revocation configurations, it will be added to the end of the List of revocation configurations.

setKeyAndCertContainer

public void setKeyAndCertContainer(KeyAndCertContainer info)

Sets the key and certificate container object which is required for OCSP request signing. This method should not need to be called by a local application.

Parameters:

info - The KeyAndCertContainer used to store key material

parsePropertiesFile

public void parsePropertiesFile(java.io.InputStream file)
                         throws java.io.FileNotFoundException,
                                java.io.IOException

Parses a revocation configuration based on a properties file and maps it into the specified revocation order. Any existing configuration is over written with the new configuration specified in the properties file.

For example, the following configuration file could be used:

   #Revocation Configuration file written by Entrust
   #Written on: Mon Jun 05 16:23:29 EDT 2006
  
   # OCSP Configuration number: 0
   ocspconfig.name.0 = config0
   config0.aiachecking = true
   config0.connecttimeout = 0
   config0.readtimeout = 0
   config0.includerequestorname = true
   config0.includeacceptableresponse = false
   config0.nonce = false
   config0.certidhashalgorithm = sha256
 
   # OCSP Configuration number: 1
   ocspconfig.name.1 = config1
   config1.accesslocation = http://responder2.location.com:80
   config1.aiachecking = true
   config1.connecttimeout = 0
   config1.readtimeout = 0
   config1.includerequestorname = true
   config1.includeacceptableresponse = false
   config1.nonce = false
   config1.certidhashalgorithm = sha256
   config1.cadn.0 = o=responder2,c=ca
 
   # OCSP Configuration number: 2
   ocspconfig.name.2 = config2
   config2.accesslocation = http://responder3.location.com:80
   config2.aiachecking = false
   config2.connecttimeout = 0
   config2.readtimeout = 0
   config2.includerequestorname = true
   config2.includeacceptableresponse = false
   config2.nonce = false
   config2.certidhashalgorithm = sha256
   config2.cadn.0 = o=responder3,c=ca
 
   # CRL Configuration: 
   crl.requirecrl = true
   crl.enableofflinelookup = false
   crl.revstores = default
   crl.revstore.0 = com.entrust.toolkit.x509.revocation.CachedCRLRS
   crl.revstore.1 = com.entrust.toolkit.x509.revocation.DirectoryCRLRS
   crl.revstore.2 = com.entrust.toolkit.x509.revocation.HttpCRLRS     
 
   # Revocation configuration order defined below
   localconfig.0 = config0
   localgroup.1 = config1:config2
   crlconfig.2 = true
 
 

Note: The key values are not case sensitive.

See the Programmers guide for more information on the parameters and values which can be used in this configuration file

Parameters:

file - An InputStream containing the ocspconfiguraiton.properties file

Throws:

java.io.IOException - if an IO error occurs reading the properties file,

java.io.FileNotFoundException - if the specified file could not be found

writePropertiesFile

public void writePropertiesFile(java.io.OutputStream filename,
                                java.lang.String certLocation)

Write the current Revocation Configuration which this class represents to the specified OutputStream. The data written to the OutputStream will be in the format of a standard java properties file. The data will be written as follows:

1. The current revocation order will be determined by calling the getRevocationConfigList() method.

2. For each element in the list, the configuration parameters will be written out as follows:

• If the RevocationConfigItem is of type OCSP, the corresponding OCSPConfiguration will be written to the properties file.
• If the RevocationConfigItem is of type OCSPGROUP, each OCSPConfiguration in the group will be written out separately
• If the RevocationConfigItem is of type CRL, no configuration will be written out

Note: When an OCSP configuration contains responder certificates, or signing certificates, these certificates will be written to either the supplied location, or the current directory if no valid location is specified.

3. A generic name will be chosen for each configuration, starting with config0, config1 ... configN. After all the configurations are written out, the revocation order will be specified, and the corresponding configuration will be mapped to proper configuration.

Parameters:

filename - the filename that will be used to write the propeties file

certLocation - the location where certificates should be written