com.entrust.toolkit.x509.certstore

Class CollectionCS

java.lang.Object

com.entrust.toolkit.x509.certstore.CertificateStore

com.entrust.toolkit.x509.certstore.CollectionCS

public final class CollectionCS
extends CertificateStore

This certificate store manages other certificate stores and is the entry point for certificate validation.

Constructor Summary

Constructors

Constructor and Description
CollectionCS(ValidationInfo validationInfo) Creates a new CollectionCS and initializes it for the logged in user.

Method Summary

Modifier and Type	Method and Description
void	addTrustedCertificate(X509Certificate trustedCert) Adds a trusted certificate.
void	addTrustedCertificate(X509Certificate trustedCert, boolean checkPABPolicy) Adds a trusted certificate.
void	addTrustedCertificates(X509Certificate[] trustedCerts) Adds trusted certificates, setting them as roots of trust.
void	attach(CertificateStore certStore) Adds a new certificate store to the set of certificate stores managed by this CollectionCS.
CertificateSet	findAllCerts(java.security.Principal dn) Finds all certificates in this collection of certificate stores that are stored under the indicated distinguished name.
CertificateSet	findCerts(GeneralName location) Generalized version of findCerts.
CertificateSet	findCerts(java.security.Principal dn) Returns all certificates for the entity specified in dn.
CertificateSet	findExtensionCerts(X509Certificate certificate, ObjectID accessMethod, ObjectID infoAccess) Search through all certificate stores for certificates located at the AIA ca-Issuers accessLocation.
java.util.List<CertificateStore>	getCertificateStores() Returns a List of CertificateStore object that will be used by this CollectionCS to find certificates.
X509Certificate[]	getRootsOfTrust() Method getRootsOfTrust
X509Certificate[]	getTrustedCertificates() Method getTrustedCertificates.
ValidationConfig	getValidationConfig() This methods collection the configuration settings used by this object and constructs a ValidationConfig object that represent this validation settings in use by this object.
boolean	isTrustedCertificate(X509Certificate certificate) Indicates whether or not the certificate is a trusted certificate.
void	setValidationConfig(ValidationConfig validationConfig) This method is used for setting the Validation Configuration, which allows custom validation parameters to be set.
X509Certificate[]	validate(X509Certificate certificate) Validates an X.509 certificate.
X509Certificate[]	validate(X509Certificate certificate, java.util.Date validationTime) Validates an X.509 certificate at a given point in time.

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

Constructor Detail

CollectionCS

public CollectionCS(ValidationInfo validationInfo)
             throws java.lang.NullPointerException

Creates a new CollectionCS and initializes it for the logged in user.

Parameters:

validationInfo - the validation info that contains the environment for the certificate validation process

Throws:

java.lang.NullPointerException - if validationInfo is null

Method Detail

addTrustedCertificate

public void addTrustedCertificate(X509Certificate trustedCert)
                           throws CertificationRootException

Adds a trusted certificate.

This method calls method addTrustedCertificate(X509Certificate, boolean) with a boolean value of true, indicating the CA PAB and PAB policy settings will be checked for this setting.

Parameters:

trustedCert - the new trusted certificate to be added

Throws:

CertificationRootException - if the policy doesn't allow PABs or CA PABs.

addTrustedCertificate

public void addTrustedCertificate(X509Certificate trustedCert,
                                  boolean checkPABPolicy)
                           throws CertificationRootException

Adds a trusted certificate.

If the certificate has a BasicConstraints extension, this extension decides if the certificate is a CA certificate or not.

If the certificate does not have a BasicConstraints extension, then the certificate is considered an end user certificate. The only exception is if it is a V1 X509Certificate and ValidationInfo.getForceV1CertAsCA() is set to true.

If checkPABPolicy is true this method will perform the following policy checks:

• If the certificate is an end user certificate and the policy certificate does not allow the use of private address books (PAB), addTrustedCertificate throws a CertificationRootException.
• If the certificate is a CA certificate and the policy certificate does not allow the use of CA private address books (CA PAB), addTrustedCertificate throws a CertificationRootException.

Trusted certificates are stored in a static memory based repository. Because the repository is memory based it is non-persistent, meaning it exists only while the application is running and is not shared between separate applications.

Parameters:

trustedCert - the new trusted certificate to be added

checkPABPolicy - Set to true if checking the Personal Address Book (PAB) policy and (CAPAB) policy should be checked, false if they should not be checked

Throws:

CertificationRootException - if the policy is checked and it doesn't allow PABs or CA PABs.

addTrustedCertificates

public void addTrustedCertificates(X509Certificate[] trustedCerts)

Adds trusted certificates, setting them as roots of trust.

This method calls method addTrustedCertificate(X509Certificate, boolean) with a boolean value of false, indicating the CA PAB and PAB policy settings will not be checked for this setting.

Parameters:

trustedCerts - the new trusted certificates to be added

Since:

7.0

validate

public X509Certificate[] validate(X509Certificate certificate)
                           throws CertificationException

Validates an X.509 certificate.

Validation consists of three steps:

1. Find a certificate chain from certificate to the root of trust
2. Validate the chain with all certificate extensions
3. Verify that no certificate in the chain is revoked

This may cause the Directory to be contacted, which could cause this call to run for a long time if the Directory is slow to respond. If possible, set Directory connection and search timeout values.

The validation of a trusted certificate does not check its extension and revocation.

Parameters:

certificate - the certificate to validate

Returns:

The valid certificate chain from the root of trust to the given certificate.

Throws:

CertificationRootException - thrown if no certificate chain from certificate to the root of trust can be found

LifespanException - if certificate is not yet valid or has already expired

ExtensionException - thrown if a certificate chain is found, but chain validation fails

RevocationException - thrown if a certificate chain is found, but a certificate in the chain is revoked

CertificationException

validate

public X509Certificate[] validate(X509Certificate certificate,
                                  java.util.Date validationTime)
                           throws CertificationException

Validates an X.509 certificate at a given point in time.

Validation consists of three steps:

1. Find a certificate chain from certificate to the root of trust
2. Validate the chain with all certificate extensions
3. Verify that no certificate in the chain is revoked

This may cause the Directory to be contacted, which could cause this call to run for a long time if the Directory is slow to respond. If possible, set Directory connection and search timeout values.

The validation of a trusted certificate does not check its extension or revocation.

Parameters:

certificate - the certificate being validated

validationTime - the time at which the validation is being done for

Returns:

the valid certificate chain from the root of trust to the given certificate; null if the certificate is revoked after validation time

Throws:

CertificationRootException - thrown if no certificate chain from certificate to the root of trust can be found

LifespanException - thrown if the certificate is not yet valid at the time of validation or has already expired at the time of validation

ExtensionException - thrown if a certificate chain is found, but chain validation fails

RevocationException - thrown if a certificate chain is found, but a certificate in the chain is revoked; the revocation status of the certificate is checked a the time of validation, for all other certificates in the chain the revocation status is checked at the current time

RevocationWarningException - thrown if the certificate is revoked, but was revoked after the time of validation

CertificationException

Since:

7.0

findCerts

public CertificateSet findCerts(java.security.Principal dn)

Returns all certificates for the entity specified in dn. If no certificate is found, this method returns null.

Specified by:

findCerts in class CertificateStore

Parameters:

dn - the distinguished name of the key owner

Returns:

the certificates of dn or null if no certificates for dn are found in this CertificateStore

Since:

7.0

findAllCerts

public CertificateSet findAllCerts(java.security.Principal dn)

Finds all certificates in this collection of certificate stores that are stored under the indicated distinguished name.

Note: Each individual certificate store in the collection is searched; this differs from the findCerts(Principal) API which stops after certificates are found in any of the certificate stores in the collection.

Parameters:

dn - the distinguished name that will be used in the certificate lookup

Returns:

the set of certificates found during the lookup (empty if no certificates were found)

Since:

8.0

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.

attach

public void attach(CertificateStore certStore)

Adds a new certificate store to the set of certificate stores managed by this CollectionCS.

If a certificate cannot be found in any of the default certificate stores, it is searched for in certStore.

Parameters:

certStore - an additional certificate store to use when looking for a certificate

getCertificateStores

public java.util.List<CertificateStore> getCertificateStores()

Returns a List of CertificateStore object that will be used by this CollectionCS to find certificates.

Returns:

A List of CertificateStore objects

isTrustedCertificate

public boolean isTrustedCertificate(X509Certificate certificate)

Indicates whether or not the certificate is a trusted certificate.

Parameters:

certificate - the certificate to check

Returns:

Returns true if the certificate is a trusted certificate, otherwise returns false.

getTrustedCertificates

public X509Certificate[] getTrustedCertificates()

Method getTrustedCertificates.

Returns:

all certificates in the CertificateGraph singleton.

Since:

7.0

getRootsOfTrust

public X509Certificate[] getRootsOfTrust()

Method getRootsOfTrust

Returns:

all roots of trust in the CertificateGraph singleton

Since:

7.0

findExtensionCerts

public CertificateSet findExtensionCerts(X509Certificate certificate,
                                         ObjectID accessMethod,
                                         ObjectID infoAccess)
                                  throws CertificationException

Search through all certificate stores for certificates located at the AIA ca-Issuers accessLocation. Return an array of all the certificates found.

Parameters:

certificate -

Returns:

A CertificateSet containing the certificates found using the specified extension

Throws:

CertificationException

setValidationConfig

public void setValidationConfig(ValidationConfig validationConfig)

This method is used for setting the Validation Configuration, which allows custom validation parameters to be set.

Parameters:

validationConfig - The validationConfig

Since:

8.0

See Also:

ValidationConfig

getValidationConfig

public ValidationConfig getValidationConfig()

This methods collection the configuration settings used by this object and constructs a ValidationConfig object that represent this validation settings in use by this object.

Returns:

The ValidationConfig object that represents the settings that are used by this ColletionCS object

Since:

8.0

See Also:

ValidationConfig