com.entrust.toolkit.x509.revocation

Class ArchiveCRLCache

java.lang.Object

com.entrust.toolkit.x509.revocation.RevocationStore

com.entrust.toolkit.x509.revocation.ArchiveCRLCache

Direct Known Subclasses:

ArchiveBinaryCRLCache

public class ArchiveCRLCache
extends RevocationStore

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

An archive CRL cache provided the ability to read and write from Entrust's .CRL and .ARL file formats. These files both represent archives are CRLs and ARLs respectively.

This class can be used in two main ways. It can be used as a RevocationStore object, providing access to revocation lists that could not be retrieved otherwise — after a user has logged in with no Directory connection, for example. In this case, the archive CRL cache must first be initialized and then added to the user's collection of revocation stores. This can be done as follows:

     ValidationInfo validationInfo = user.getCertVerifier();
     ArchiveCRLCache archiveCrlCache = new ArchiveCRLCache(inputStream, validationInfo);
     user.getRevocationStore().attach(archiveCrlCache);
 

It can also be used to provide persistent storage of all CRLs in a user's memory CRL cache. To do this, before the application terminates, call addMemoryCache to store all CRLs currently held in the user's memory CRL cache in the archive CRL cache, and then call write to store archive CRL cache to a persistent location (disk). Then, when the application is run again, after the user has logged in, all the CRLs in the archive CRL cache can be loaded back into the user's memory CRL cache by calling initMemoryCache(com.entrust.toolkit.x509.revocation.CachedCRLRS). In this case, the archive does not need to be attached to the user's collection of revocation stores..

Field Summary

Fields

Modifier and Type	Field and Description
static int	ARL_ONLY Specifies that only ARLs should be written during a write operation.
static int	CRL_AND_ARL Specifies that both CRLs and ARLs should be written during a write operation.
static int	CRL_ONLY Specifies that only CRLs should be written during a write operation.

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

m_enableOfflineLookup, m_validationInfo

Constructor Summary

Constructors

Constructor and Description
ArchiveCRLCache(java.io.InputStream is, ValidationInfo validationInfo) The constructor; creates a new ArchiveCRLCache object initializing it with data read from the provided input stream.
ArchiveCRLCache(ValidationInfo validationInfo) The constructor; creates a new empty ArchiveCRLCache object.

Method Summary

Methods

Modifier and Type	Method and Description
void	addCRL(DistPointAndCRL dpcrl) Adds the CRL to the archive CRL cache.
void	addCRLs(DistPointAndCRL[] dpcrls) Adds the CRLs to the archive CRL cache.
void	addMemoryCache(CachedCRLRS memoryCrlCache) Adds all the CRLs contained in the provided memory CRL cache to this archive CRL cache.
void	cleanup() Removes all expired CRLs from this archive CRL cache.
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.
void	initMemoryCache(CachedCRLRS memoryCrlCache) Adds the CRLs contained in this archive CRL cache to the provided memory CRL cache.
void	parse(java.io.InputStream inputStream) Parses an input stream containing an archive CRL cache in Entrust revocation list cache format.
void	removeCRL(ASN1Type distributionPointName) Removes all CRLs contained in the archive CRL cache under the indicated distribution point.
void	write(java.io.OutputStream outputStream, int writeMode) Writes the acrhive CRL cache to an output stream in Entrust revocation list cache format.

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

CRL_ONLY

public static final int CRL_ONLY

Specifies that only CRLs should be written during a write operation.

See Also:

Constant Field Values

ARL_ONLY

public static final int ARL_ONLY

Specifies that only ARLs should be written during a write operation.

See Also:

Constant Field Values

CRL_AND_ARL

public static final int CRL_AND_ARL

Specifies that both CRLs and ARLs should be written during a write operation.

See Also:

Constant Field Values

Constructor Detail

ArchiveCRLCache

public ArchiveCRLCache(ValidationInfo validationInfo)

The constructor; creates a new empty ArchiveCRLCache object.

Following creation, the archive CRL cache is empty, it does not contain any CRLs. CRLs can be manually added using the add APIs, or CRLs can be loaded from an archive cache file using the parse API.

Parameters:

validationInfo - the validation information that will be used during the validation of the CRLs this CRL revocation store contains.

ArchiveCRLCache

public ArchiveCRLCache(java.io.InputStream is,
               ValidationInfo validationInfo)
                throws UserFatalException

The constructor; creates a new ArchiveCRLCache object initializing it with data read from the provided input stream.

Following creation, CRLs are automatically loaded into the CRL archive cache by parsing them from the input stream. The input stream must represent a valid CRL archive cache format; this is Entrust's .CRL or .ARL file format.

Parameters:

validationInfo - the validation information that will be used during the validation of the CRLs this CRL revocation store contains.

Throws:

UserFatalException - if there is an error parsing the data in input stream

Method Detail

addCRL

public void addCRL(DistPointAndCRL dpcrl)

Adds the CRL to the archive CRL cache.

The CRL is added under the distribution point from which it was originally retrieved.

Parameters:

dpcrl - the CRL and the distribution point from which it was retrieved

addCRLs

public void addCRLs(DistPointAndCRL[] dpcrls)

Adds the CRLs to the archive CRL cache.

The CRLs are added under the distribution point from which each was originally retrieved.

Parameters:

dpcrls - the CRLs and the distribution points from which they were retrieved

addMemoryCache

public void addMemoryCache(CachedCRLRS memoryCrlCache)

Adds all the CRLs contained in the provided memory CRL cache to this archive CRL cache.

Note

Be careful when using this method; depending on the size of the memory CRL cache, there is the potential for massive growth of the archive CRL cache.

Parameters:

memoryCrlCache - the memory CRL cache

cleanup

public void cleanup()

Removes all expired CRLs from this archive CRL cache.

A CRL is considered to have expired if the current time/date is not before the next update time/date, taking into account the CRL grace period from the client settings.

initMemoryCache

public void initMemoryCache(CachedCRLRS memoryCrlCache)

Adds the CRLs contained in this archive CRL cache to the provided memory CRL cache.

CRLs that exist in the archive CRL cache and have expired are not added to the memory CRL cache. A CRL is considered to have expired if the current time/date is not before the next update time/date (or expiry time/date), taking into account the CRL grace period from the client settings.

Parameters:

memoryCrlCache - the memory CRL cache

parse

public void parse(java.io.InputStream inputStream)
           throws UserFatalException

Parses an input stream containing an archive CRL cache in Entrust revocation list cache format.

All CRLs found in input stream are added to this archive CRL cache. Typically, an archive CRL cache in Entrust revocation list cache format is contained in files with a .CRL or .ARL extension.

Parameters:

inputStream - an input stream containing an archive CRL cache in Entrust revocation list format

Throws:

UserFatalException - if an error occurs while parsing the data contained in the input stream; indicates an improperly formatted Entrust revocation list cache

removeCRL

public void removeCRL(ASN1Type distributionPointName)

Removes all CRLs contained in the archive CRL cache under the indicated distribution point.

CRLs contained in an archive CRL cache, unlike those contained in a memory CRL cache, are not automatically removed when they expire. This method provides a way to remove all CRLs contained in the cache under a specific distribution point.

Parameters:

distributionPointName - the name of the distribution point under which all CRLs contained in the archive CRL cache are to be removed

write

public void write(java.io.OutputStream outputStream,
         int writeMode)
           throws java.lang.IllegalArgumentException,
                  java.security.cert.CRLException

Writes the acrhive CRL cache to an output stream in Entrust revocation list cache format.

The output stream is not closed by this API, it is up to the caller to do so when appropriate. The write mode gives the caller control over which types of RLs are written. The following modes are permitted:

• CRL_ONLY — only write CRLs (RLs that only contain revocation information about user certificates)
• ARL_ONLY — only write ARLs (RLs that only contain revocation information about CA certificates)
• CRL_AND_ARL — write both CRLs and ARLs.

Parameters:

outputStream - the output stream the archive CRL cache will be written to

writeMode - allows the caller to control which types of CRLs are written

Throws:

java.lang.IllegalArgumentException - if the write mode is not permitted

java.security.cert.CRLException - thrown in the error occurred while DER encoding one of the CRL contained in the archive CRL cache

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.

Specified by:

getCrlsByType in class RevocationStore

Parameters:

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

crlType - the type of CRLs to be loaded

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

Returns:

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

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