iaik.x509

Class ChainVerifier

java.lang.Object

iaik.x509.ChainVerifier

Direct Known Subclasses:

SimpleChainVerifier

public abstract class ChainVerifier
extends java.lang.Object

This class provides a framework that allows you to verify certificate chains. It implements the cryptographic verification logic, but has to be subclassed for the trust verification, see the SimpleChainVerifier class for a basic implementation of such logic.

See the documentation of the verifyChain method for more information about the verification that is performed.

NOTE: This class currently includes only a very basic support for X.509v3 extensions.

Version:

1.1

See Also:

SimpleChainVerifier

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ChainVerifier() Constructor for use by subclasses.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	checkExtensions(java.security.cert.X509Certificate[] certificateChain, int index) Verifies if the extensions in the certificate at the given index in the certificate chain are valid.
abstract boolean	isTrustedCertificate(java.security.cert.X509Certificate cert) Tests whether the given certificate is explicitly trusted.
static java.security.cert.X509Certificate[]	orderCertificateChain(java.security.cert.X509Certificate leaf, java.security.cert.X509Certificate[] certs) Reorder a set of certificates so that it becomes a valid chain.
boolean	verifyChain(java.security.cert.X509Certificate[] certificateChain) This method verifies a certificate chain.
boolean	verifyChain(java.security.cert.X509Certificate[] certificateChain, boolean reversed) This method verifies a (reversed) certificate chain.

Methods inherited from class java.lang.Object

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

Constructor Detail

ChainVerifier

protected ChainVerifier()

Constructor for use by subclasses.

Method Detail

isTrustedCertificate

public abstract boolean isTrustedCertificate(java.security.cert.X509Certificate cert)
                                      throws java.security.cert.CertificateException

Tests whether the given certificate is explicitly trusted. This method has to be implemented by subclasses, which will typically check the certificate against a list (or some other database) of trusted certificates. This method may also throw a certificate exception if there is trouble with the given certificate, but this is not recommended in normal use. The exception will be directly passed through by verifyChain.

Parameters:

cert - the certificate to be checked

Returns:

true if the certificate shall be trusted, false if not

Throws:

java.security.cert.CertificateException

verifyChain

public boolean verifyChain(java.security.cert.X509Certificate[] certificateChain)
                    throws java.security.cert.CertificateException

This method verifies a certificate chain. The user certificate must be at index 0 with increasing indices towards the top level certificate at n-1. The method will walk through the chain starting at the user certificate searching for trusted certificates and verifying the certificate signatures on the way. As soon as a trusted certificate is found, the method returns true, the rest of the chain is not verified cryptographically (as a certificate explicitly marked trusted was already found). If no trusted certificate is found but the chain verifies ok it returns false. If there is some error in the chain, e.g. a certificate does not verify or is expired, it throws a CertificateException.

Parameters:

certificateChain - the certificate chain to be checked

Returns:

true, if a valid path from the client certificate to a trusted signer can be built and verified

Throws:

java.security.cert.CertificateException - if there is some error in the certificate chain

checkExtensions

protected void checkExtensions(java.security.cert.X509Certificate[] certificateChain,
                   int index)
                        throws java.security.cert.CertificateException

Verifies if the extensions in the certificate at the given index in the certificate chain are valid. If an error occurs, a CertificateException will be thrown. The chain will always contain the user certificate at index 0.

NOTE: This method currently only works for instances of iaik.x509.X509Certificate, for other subclasses of java.security.cert.X509Certificate no extension checking will be done at all.

The handling of X.509 extensions by this class is far from complete. If you want to implement your own extension checking, override this method. It is supposed to be called only by verifyChain().

Current handling of extensions:

• BasicConstraints: if a basic constraints extension is present, it must specify ca=false for the certificate at index 0 and ca=true for all others. If ca=true and pathLenConstraint is set (not equal -1) it will be checked by the index as well.
• KeyUsage: this extension is ignored for the user certificate, all other certificates have to include KeyUsage.keyCertSign if the extension is present.
• The extensions in the following list are simply ignored, no matter if they are marked critical or not, what there contents, and if they are present in the user or in the CA certificates.
  • AuthorityKeyIdentifier
  • CRLDistributionPoints
  • CRLNumber
  • ExtendedKeyUsage
  • IssuerAltName
  • PolicyConstraints
  • PolicyMappings
  • ReasonCode
  • SubjectAltName
  • SubjectKeyIdentifier
  • NetscapeBaseUrl
  • NetscapeCaPolicyUrl
  • NetscapeCaRevocationUrl
  • NetscapeCertRenewalUrl
  • NetscapeComment
  • NetscapeRevocationUrl
  • NetscapeSSLServerName
• All other non-critical extensions are ignored as well.
• All other critical extensions cause a CertificateException to be thrown. This includes among others the certificate extensions CertificatePolicies, NameConstraints, etc. which are supported by the IAIK JCE but not checked by this method.

Parameters:

certificateChain - the certificate chain containing the certificate to be checked

index - the index of the certificate to be checked

Throws:

java.security.cert.CertificateException - if the verification fails

verifyChain

public boolean verifyChain(java.security.cert.X509Certificate[] certificateChain,
                  boolean reversed)
                    throws java.security.cert.CertificateException

This method verifies a (reversed) certificate chain. If your certificate chain has the top level certificate at index 0 and the user certificate at index n-1, call this method with the reversed parameter set to true.

Parameters:

certificateChain - the certificate chain to be verified

reversed - whether the user certificate is loacted at index 0 (reversed = false), or at index n-1 (reversed = true)

Returns:

true, if a valid path from the client certificate to a trusted signer can be built and verified

Throws:

java.security.cert.CertificateException - if there is some error in the certificate chain

orderCertificateChain

public static java.security.cert.X509Certificate[] orderCertificateChain(java.security.cert.X509Certificate leaf,
                                                         java.security.cert.X509Certificate[] certs)
                                                                  throws java.security.cert.CertificateException

Reorder a set of certificates so that it becomes a valid chain. In some cases an application/ protocol might not supply you with a correctly ordered certificate chain but only give you a set of certificates. This class can build a valid certificate chain from this set. It will start at the given leaf certificate, which becomes the end of the chain and search through the set of certificates for the issuer certificates until it finds a self signed certificate. The resulting chain is then returned with the leaf certificate at index 0.

Parameters:

leaf - the leaf certificate

certs - the certificate chain to be reordered

Returns:

the reordered certificate chain

Throws:

java.security.cert.CertificateException - if a required issuer certificate cannot be found in the set of certificates.