com.entrust.toolkit.x509.revocation

Class CachedCRLRS

java.lang.Object

com.entrust.toolkit.x509.revocation.RevocationStore

com.entrust.toolkit.x509.revocation.CachedCRLRS

public final class CachedCRLRS
extends RevocationStore

An implementation of an X.509 revocation store that represents a memory CRL cache.

A memory CRL cache provides the best performance of all of Entrust's revocation store implementations. It holds the X.509 CRLs as already parsed X509CRL objects in memory.

By default, a user's revocation checking mechanism (CollectionRS) has a memory CRL cache attached. When searching for CRLs, this revocation store is always searched first; others are only searched if appropriate CRLs could not be found in the memory CRL cache. Any time CRLs are retrieved from another revocation store (not the memory CRL cache) that is attached to the user's revocation checking mechanism, the memory CRL cache is automatically updated with the retrieved CRLs.

The cache keeps itself current by automatically removing all non-current CRLs under the distribution points from which they were retrieved. This process occurs every time an attempt is made to retrieve CRLs from the cache. A CRL is non-current when the CRL entry lifetime has been exceeded (stale) or when the CRL 'notAfter' time has been exceeded taking into account the CRL grace period (expired). The CRL grace period is a client policy setting that specifies an additional amount of time after the 'nextUpdate' date that a CRL will be considered unexpired.

See Also:

CollectionRS

Field Summary

Fields

Modifier and Type	Field and Description
long	DEFAULT_CACHE_ENTRY_LIFETIME By default, the amount of time in milliseconds that a CRL will be stored in the cache before it is considered stale and removed.

Fields inherited from class com.entrust.toolkit.x509.revocation.RevocationStore

m_enableOfflineLookup, m_validationInfo

Constructor Summary

Constructors

Constructor and Description
CachedCRLRS(ValidationInfo validationInfo) The constructor; creates and initializes a new CachedCRLRS object.

Method Summary

Modifier and Type	Method and Description
void	flush() Flushes the cache; removes all CRLs from the cache.
long	getCacheEntryLifetime() Returns the cache entry lifetime in milliseconds.
DistPointAndCRL[]	getCRLs() Returns all the X.509 CRLs contained in this revocation store as an array of DistPointAndCRL objects, from which specific distribution points and CRLs can be retrieved.
protected GeneralName	getCrlsByType(java.util.Collection crls, CRLType crlType, GeneralNames dpDistributionPoint) Retrieves all CRLs of the indicated type that exist at the indicated distrubution point.
protected java.lang.String	getName() Returns the name of this X.509 CRL revocation store.
boolean	isDisabled() Indicates whether or not the cache is enabled/disabled.
void	removeCRLs(GeneralName distributionPointName) Removes all CRLs from the cache that are stored under the indicated distribution point name.
void	setCacheEntryLifetime(long cacheEntryLifetime) Sets the cache entry lifetime in milliseconds.
void	setDisabled(boolean disabled) Allows this cache to be enabled/disabled.

Methods inherited from class com.entrust.toolkit.x509.revocation.RevocationStore

enableOfflineLookup

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CACHE_ENTRY_LIFETIME

public long DEFAULT_CACHE_ENTRY_LIFETIME

By default, the amount of time in milliseconds that a CRL will be stored in the cache before it is considered stale and removed.

Constructor Detail

CachedCRLRS

public CachedCRLRS(ValidationInfo validationInfo)

The constructor; creates and initializes a new CachedCRLRS object.

Parameters:

validationInfo - the user's certificate validation information (provides access to the user's directory)

Method Detail

getCRLs

public DistPointAndCRL[] getCRLs()

Returns all the X.509 CRLs contained in this revocation store as an array of DistPointAndCRL objects, from which specific distribution points and CRLs can be retrieved.

All CRLs retrieved from the memory CRL cache using this API are always current; no stale CRLs (cache entry lifetime exceeded) or expired CRLs ('nextUpdate' time reached). Non-current CRLs are automatically removed from the cache.

Returns:

the X.509 CRLs as an array of DistPointAndCRL objects

getCacheEntryLifetime

public long getCacheEntryLifetime()

Returns the cache entry lifetime in milliseconds.

The cache entry lifetime inticates the amount of time that a CRL will be stored in the cache before it is considered stale and automatically removed.

Returns:

the cache entry lifetime in milliseconds

Since:

7.2

setCacheEntryLifetime

public void setCacheEntryLifetime(long cacheEntryLifetime)

Sets the cache entry lifetime in milliseconds.

The cache entry lifetime indicates the amount of time that a CRL will be stored in the cache before it is considered stale and automatically removed.

The cache entry lifetime cannot be set to a value less than 0; attempts to do so will result in the DEFAULT_CACHE_ENTRY_LIFETIME being used.

Parameters:

cacheEntryLifetime - the cache entry lifetime in milliseconds

Since:

7.2

removeCRLs

public void removeCRLs(GeneralName distributionPointName)

Removes all CRLs from the cache that are stored under the indicated distribution point name.

Parameters:

distributionPointName - the distribution point name under which all stored CRLs will be removed

Since:

7.2

flush

public void flush()

Flushes the cache; removes all CRLs from the cache.

Since:

7.2

setDisabled

public void setDisabled(boolean disabled)

Allows this cache to be enabled/disabled.

By default, the cache will be enabled. When the cache is disabled, it will not be used (checked or updated) by the certificate revocation checking mechanism. By disabling the cache you can ensure that CRLs will always be retrieved from another revocation store (Directory based, HTTP based, ...). This can be useful for applications that always require current CRLs and are not concerned with the performance penalty involved with not using a cache.

Disabling the cache only disables it usage by the certificate revocation checking mechanism. All public APIs will still operate identically to when the cache is enabled.

Parameters:

disabled - true to disable the cache; false to enable the cache

Since:

7.2

isDisabled

public boolean isDisabled()

Indicates whether or not the cache is enabled/disabled.

Returns:

true if the cache is disabled; false otherwise

Since:

7.2

getName

protected java.lang.String getName()

Returns the name of this X.509 CRL revocation store.

Specified by:

getName in class RevocationStore

Returns:

the name of the this X.509 CRL revocation store

getCrlsByType

protected GeneralName getCrlsByType(java.util.Collection crls,
                                    CRLType crlType,
                                    GeneralNames dpDistributionPoint)

Retrieves all CRLs of the indicated type that exist at the indicated distrubution point.

Any CRLs that are retrieved are be added to the collection of X.509 CRLs in iaik.x509.X509CRL format. Also, all CRLs retrieved from the memory CRL cache using this API are always current; no stale CRLs (cache entry lifetime exceeded) or expired CRLs ('nextUpdate' time reached). Non-current CRLs are automatically removed from the cache.

Checking is not done to see if any of the the X.509 CRLs that are retrieved and add to the collection already exist in the collection. It is assumed that the collection passed in will be empty, and thus duplicate entries need not be considered (unless the cache could contain duplicate CRLs at a single distribution point which it cannot).

When the cache has been disabled, this method does not do anything.

Specified by:

getCrlsByType in class RevocationStore

Parameters:

crls - a collection of X.509 CRLs in X509CRL format; all retrieved CRLs will be added to this collection

crlType - the type of CRLs to be retrieved; ignored by this implementation, all available CRLs at the distribution point are returned

dpDistributionPoint - the distribution point in GeneralNames format from which the CRLs will be retrieved

Returns:

a GeneralName representation of the distribution point name the CRLs were retrieved from if any were in fact retrieved; null otherwise