com.entrust.toolkit.x509.certstore

Class ArchiveCertCache

java.lang.Object

com.entrust.toolkit.x509.certstore.CertificateStore

com.entrust.toolkit.x509.certstore.ArchiveCertCache

public class ArchiveCertCache
extends CertificateStore

ArchiveCertCache is used to read and write the Entrust .CCH and .XCC certificate cache files, used to store user certificates and cross certificates respectively.

This class can be used in two different ways. It can be used as a traditional CertificateStore object, providing access to certificates that could not be retrieved otherwise — when a User is logging in with no Directory connection, for example. In this case, initialize the certificate cache and add it to the main certificate store using the following code:

     ArchiveCertCache archiveCertCache = new ArchiveCertCache(inputStream);
     user.getCertificateStore().attach(archiveCertCache);
 

ArchiveCertCache can also be used to hold all certificates in the memory cache, and to put them back into memory when a program starts up again. In this case, use the methods addMemoryCache and initMemoryCache(). Before ending the application, call addMemoryCache() to add all certificates currently in memory to the cache object, and then write out the cache object. When starting the application, call initMemoryCache(), which adds all certificates in the archive to the memory cache. In this case, the archive does not need to be added as a certificate store.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CROSS_CERT_ONLY Specifies that only cross certificates should be written.
static int	USER_AND_CROSS_CERT Specifies that both user certificates and cross certificates should be written.
static int	USER_CERT_ONLY Specifies that only user certificates should be written.

Constructor Summary

Constructors

Constructor and Description
ArchiveCertCache() Creates an empty archive cache.
ArchiveCertCache(java.io.InputStream is) Creates an archive cache, and initializes it with the contents of the cache file specified by the InputStream argument.

Method Summary

Modifier and Type	Method and Description
void	addCertificate(X509Certificate cert) Adds the specified certificate to this cache.
void	addCertificates(X509Certificate[] certs) Adds the specified certificates to this cache.
void	addMemoryCache() Adds all certificates currently in the main certificate graph to this cache object.
void	cleanup() Removes all certificates from the cache that have passed their notAfter usage period, and are no longer valid.
CertificateSet	findCerts(GeneralName location) Generalized version of findCerts.
CertificateSet	findCerts(java.security.Principal dn) Returns all certificates currently in the certificate cache that belong to the specified DN.
void	initMemoryCache() Adds all certificates currently in the cache object to the main certificate graph.
void	parse(java.io.InputStream cacheFile) Adds the contents of an archive cache (.CCH or .XCC) to the cache object.
void	write(java.io.OutputStream os, int writeMode) Writes the certificates contained in this cache object to a stream, in the Entrust certificate cache format.

Methods inherited from class com.entrust.toolkit.x509.certstore.CertificateStore

find

Methods inherited from class java.lang.Object

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

Field Detail

USER_CERT_ONLY

public static int USER_CERT_ONLY

Specifies that only user certificates should be written.

CROSS_CERT_ONLY

public static int CROSS_CERT_ONLY

Specifies that only cross certificates should be written.

USER_AND_CROSS_CERT

public static int USER_AND_CROSS_CERT

Specifies that both user certificates and cross certificates should be written.

Constructor Detail

ArchiveCertCache

public ArchiveCertCache()

Creates an empty archive cache.

ArchiveCertCache

public ArchiveCertCache(java.io.InputStream is)
                 throws UserFatalException

Creates an archive cache, and initializes it with the contents of the cache file specified by the InputStream argument.

Parameters:

is - the .CCH or .XCC certificate cache to be read. This stream is closed by this call.

Throws:

UserFatalException - if there is an error reading the protected entries in the cache file.

Method Detail

findCerts

public CertificateSet findCerts(java.security.Principal dn)

Returns all certificates currently in the certificate cache that belong to the specified DN.

Specified by:

findCerts in class CertificateStore

Parameters:

dn - the DN for which to find matching certificates.

Returns:

the certificates belonging to dn, or null if no certificates for dn are found in this CertificateStore

Since:

7.0

addCertificate

public void addCertificate(X509Certificate cert)

Adds the specified certificate to this cache.

Parameters:

cert - the certificate to add to the cache.

addCertificates

public void addCertificates(X509Certificate[] certs)

Adds the specified certificates to this cache.

Parameters:

certs - the certificates to add to the cache.

addMemoryCache

public void addMemoryCache()

Adds all certificates currently in the main certificate graph to this cache object.

Using this method makes the certificates easy to retrieve. Use this method in combination with initMemoryCache as the easiest way to use the certificate archive cache.

initMemoryCache

public void initMemoryCache()

Adds all certificates currently in the cache object to the main certificate graph.

Using this method makes the certificates easily available to the certificate validation algorithm. Use this method in combination with addMemoryCache as the easiest way to use the certificate archive cache.

cleanup

public void cleanup()

Removes all certificates from the cache that have passed their notAfter usage period, and are no longer valid.

The method is used to prevent runaway growth of the cache file, since certificates in the cache never expire otherwise.

write

public void write(java.io.OutputStream os,
                  int writeMode)
           throws UserFatalException,
                  java.lang.IllegalArgumentException

Writes the certificates contained in this cache object to a stream, in the Entrust certificate cache format.

The method can write the user certificates only (to create an Entrust .CCH file), the cross certificates only (to create an Entrust .XCC file), or it can write both user certificates and cross certificates.

Parameters:

os - the stream to which to write the archive cache. This stream is not closed by this call.

writeMode - one of:

• USER_CERT_ONLY — to write user certificates.
• CROSS_CERT_ONLY — to write cross certificates.
• USER_AND_CROSS_CERT — to write both user and cross certificates.

Throws:

UserFatalException - if there is an error protecting the entries in the cache.

java.lang.IllegalArgumentException - if writeMode is not one of the listed modes.

parse

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

Adds the contents of an archive cache (.CCH or .XCC) to the cache object.

Parameters:

cacheFile - a stream containing the cache file to read. This stream is closed after this call completes.

Throws:

UserFatalException - if there is an error reading the protected entries in the cache file.

findCerts

public CertificateSet findCerts(GeneralName location)
                         throws CertificationException

Generalized version of findCerts. In this case, only proceed if the GeneralName is an instance of the Principal class, otherwise return null because Certificates cannot be found by this class.

Overrides:

findCerts in class CertificateStore

Parameters:

location - The GeneralName. It must represent a type of java.security.Principal or this check cannot be done.

Returns:

the certificates belonging to location, or null if no certificates for location are found in this CertificateStore

Throws:

CertificationException - if there is a problem finding the certificates.