iaik.security.ssl
Class ChainVerifier

java.lang.Object
  |
  +--iaik.security.ssl.ChainVerifier

Direct Known Subclasses:

EntrustChainVerifier

public class ChainVerifier

extends java.lang.Object

A ChainVerifier object keeps track of trusted certificates and verifies certificate chains. It is used in peer authentication, both on the client and on the server side. The class is application extensible, i.e. the iSaSiLk distribution contains a fairly basic X.509v1 style implementation (for example, it does not handle X.509v3 extensions and has no kind of revocation checking) that can be replaced by a more advanced one if desired.

This documentation describes the default implementation, which all other implementations have to be compatible with. Note that during the handshake the library only calls two methods:

1. verifyChain() to verify certificate chains.
2. getTrustedPrincipalsArray() on the server if client authentication is enabled.

These are the only methods that have to be overridden for a custom chain verifier to function.

For more information about authentication see the separate document on Certificates and Authentication.

Field Summary

protected boolean	nullTrusted Flag indicating if null (no certificate) is trusted.
protected java.util.Hashtable	trustedCerts Hashtable containing trusted certificates mapping Principal(subject) -> X509Certificate(trusted certificate).

Constructor Summary

	ChainVerifier() Create a new ChainVerifier.
protected	ChainVerifier(int k) Constructor for use by subclasses.

Method Summary

void	addTrustedCertificate(X509Certificate cert) Add a trusted certificate.
protected X509Certificate	getIssuerCertificate(X509Certificate cert) Get the issuer certificate of the given certificate (if available in the pool of trusted certificates).
java.util.Enumeration	getTrustedPrincipals() Enumerate the explicitly trusted Principals.
Principal[]	getTrustedPrincipalsArray() Return the explicitly trusted Principals.
protected boolean	isTrustedCertificate(X509Certificate cert) Check is the certificate is explicitly trusted.
void	removeTrustedCertificate(X509Certificate cert) Remove a trusted certificate.
int	size() Return the number of explicitly trusted certificates.
protected boolean	verifyCertificate(X509Certificate cert, X509Certificate issuerCert) Verify a certificate given its issuer certificates.
boolean	verifyChain(X509Certificate[] certs, SSLTransport transport) Verify a certificate chain.

Methods inherited from class java.lang.Object

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

Field Detail

trustedCerts

protected java.util.Hashtable trustedCerts

Hashtable containing trusted certificates mapping Principal(subject) -> X509Certificate(trusted certificate).

nullTrusted

protected boolean nullTrusted

Flag indicating if null (no certificate) is trusted.

Constructor Detail

ChainVerifier

protected ChainVerifier(int k)

Constructor for use by subclasses. It does not initialize any variables, the value of k is ignored. This constructor is intended for subclasses that override all methods and do not make use of the default implementations.

ChainVerifier

public ChainVerifier()

Create a new ChainVerifier. Initially the list of trusted certificates is empty.

Method Detail

addTrustedCertificate

public void addTrustedCertificate(X509Certificate cert)

Add a trusted certificate. The argument may be null to indicate that no certificate shall be trusted.

removeTrustedCertificate

public void removeTrustedCertificate(X509Certificate cert)

Remove a trusted certificate. If the certificate was not trusted this method does nothing.

size

public int size()

Return the number of explicitly trusted certificates. If this feature is not supported by a particular implementation it should return -1.

getTrustedPrincipals

public java.util.Enumeration getTrustedPrincipals()

Enumerate the explicitly trusted Principals. If this method is not supported it should return null.

getTrustedPrincipalsArray

public Principal[] getTrustedPrincipalsArray()

Return the explicitly trusted Principals. It uses size() and getTrustedPrincipals(). If those methods are not supported it returns a Principal array of size 0. This method is used in client authentication on the server side to inform the client about acceptable certificate authorities.

isTrustedCertificate

protected boolean isTrustedCertificate(X509Certificate cert)

Check is the certificate is explicitly trusted.

In the default implementation this method is only called by verifyChain() and verifyCertificate().

verifyCertificate

protected boolean verifyCertificate(X509Certificate cert,
                                    X509Certificate issuerCert)
                             throws java.lang.Exception

Verify a certificate given its issuer certificates. The issuer certificate may be null if it is not available. The method should return true to indicate that verifying of the chain should stop and return true. It should return false to proceed normally, and throw an Exception if the chain should be rejected.

The default implementation does the following in order:

1. If the certificate is explicitly trusted, return true.
2. Throw an exception if the certificate is expired.
3. If the issuer certificate is non null verify the signature of the main certificate and throw an exception if it is invalid.
4. Otherwise return false.

In other words, the method does not verify beyond explicitly trusted certificates. This method may be overridden to implement a different policy.

In the default implementation this method is only called by verifyChain().

getIssuerCertificate

protected X509Certificate getIssuerCertificate(X509Certificate cert)

Get the issuer certificate of the given certificate (if available in the pool of trusted certificates).

In the default implementation this method is called only by verifyChain().

verifyChain

public boolean verifyChain(X509Certificate[] certs,
                           SSLTransport transport)

Verify a certificate chain. The end entity certificate should be at index 0 in the array. In the default implementation the chain should either be null, a full certificate chain (up to and including the self signed root certificate), or an incomplete certificate chain. The SSLTransport argument may be null. If it is non-null it may be used to verify if the name specified in the server certificate matches the name of the server the connection is made with (using transport.getRemotePeerName()). The default implementation does not perform this check.

Note that the default implementation of this method can only be used if the methods isTrustedCertificate(), verifyCertificate(), and getIssuerCertificate() behave as described above.

The default implementation does the following in order:

1. If the chain is null, it returns true if null is trusted, otherwise false.
2. The chain is verified starting at the user certificate via verifyCert(). If any call returns true it returns true, if any throws an exception it returns false.
3. If the previous steps did not cause the method to stop it returns true if and only if size() returns 0, i.e. no certificates are trusted at all.

That means invalid certificate chains (signatures that do not verify, expired certificates) are never accepted. If trusted certificates are set only valid chains containing a trusted certificate are accepted, otherwise all valid chains are accepted.