uk.ac.cam.ucs.webauth
Class WebauthValidator

java.lang.Object
  |
  +--uk.ac.cam.ucs.webauth.WebauthValidator

public class WebauthValidator
extends Object

Implements a validator for authentication response message.

Version:
$Revision: 1.12 $ $Date: 2005/03/31 15:10:07 $

Constructor Summary
WebauthValidator(KeyStore k)
          Default constructor.
 
Method Summary
 String getKeyPrefix()
          Get the maximum expected clock skew.
 int getMaxSkew()
          Get the maximum expected clock skew.
 int getTimeout()
          Get the maximum expected transmission time for response messages, in milliseconds.
 void setKeyPrefix(String keyPrefix)
          Set the string prefix used to identify the relevant public key in the key store.
 void setMaxSkew(int maxSkew)
          Set the maximum expected difference between the clock supplying the date parameter for validate and correct time, in milliseconds.
 void setTimeout(int timeout)
          Set the maximum expected transmission time for response messages, in milliseconds.
 void validate(WebauthRequest request, WebauthResponse response)
          Perform validation tests on a WebauthResponse.
 void validate(WebauthRequest request, WebauthResponse response, long date)
          Alternate version of validate in which date on which validation is based can be specified.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WebauthValidator

public WebauthValidator(KeyStore k)
Default constructor. The timeout for the resulting object is set to 30 sec, the clock skew to 0.5s, and the key prefix to "webauth-pubkey".

The validator needs access to the public key (or occasionally keys) corresponding to the private key(s) being used by the WLS to sign responses. These keys must be available in certificates contained in the KeyStore passed to the constructor. These should be stored under aliases formed by concatenating the key prefix and the KeyID used to identify a key in a response - for example by default the key identified in a response by '2' should be stored under the alias 'webauth-pubkey2'. Note that for the correct operation of the system it is important that exactly the right set of keys are provided to the validator - new keys should be added before they start to be used by the WLS, and old keys MUST be removed once they are no longer in use since otherwise if compromised they would represent a security vulnerability.

Any KeyStore implementing the standard Java Crypto API can be used for this. The most common is the "JKS" store implemented in the "SUN" crypto provider. Such a KeyStore can either be initialised from a keystore file on disk maintained by the keytool utility, or can be initialised at run-time with certificates stored elsewhere. For example:

 import java.security.KeyStore;
 import java.security.cert.Certificate;
 import java.security.cert.CertificateFactory;

KeyStore ks = KeyStore.getInstance("JKS");
 ks.load(null, new char[] {}); // Null InputStream, no password     

CertificateFactory factory = 
     CertificateFactory.getInstance("X.509");
 Certificate cert = 
     factory.generateCertificate(new FileInputStream("pubkey2.crt"));
 ks.setCertificateEntry("webauth-pubkey2",cert);
 
Parameters:
k - A KeyStore containing the currently-valid public keys for the authentication system.
Method Detail

validate

public void validate(WebauthRequest request,
                     WebauthResponse response)
              throws WebauthException
Perform validation tests on a WebauthResponse. This involves:
  1. Checking that an acceptable combination of parameters are present in the response.
  2. Checking that 'kid', if present, corresponds to a key currently being used by the WAA.
  3. Checking that the signature, if provided, matches the data supplied.
  4. Checking that the response is recent by comparing 'issue' with the supplied date. If the supplied date is not from a clock synchronised by NTP or a similar mechanism then an allowance must be made for the maximum expected clock skew.
  5. Checking that 'url' is consistent with that in the corresponding Request.
  6. Checking that 'auth' and/or 'sso' contain values that are consistent with those in the corresponding Requestg.
Parameters:
request - The WebauthRequest object, the submission of which to the login server resulted in the WebauthResponse being validated. This is not required to be the identical object, but it should contain the same values for the following parameters as the object which did (or at least could) have caused this response: ver, url, iact, aauth. Note that the url in the request is only required to be a prefix of the url in the response.
response - The WebauthResponse object to be validated
Throws:
WebauthException - if the response fails to validate

validate

public void validate(WebauthRequest request,
                     WebauthResponse response,
                     long date)
              throws WebauthException
Alternate version of validate in which date on which validation is based can be specified.
Parameters:
request - See validate(WebauthRequest, WebauthResponse)
response - See validate(WebauthRequest, WebauthResponse)
date - The date on which validation should be based, expressed as the number of milliseconds since January 1, 1970 GMT..
Throws:
WebauthException - if the response fails to validate

setTimeout

public void setTimeout(int timeout)
Set the maximum expected transmission time for response messages, in milliseconds. A response recieved more than this time after it was issued will be considered invalid. The default is 30s, and since in some situations response transmition may require user intervention (for example to confirm a redirect) it should probably not be set much lower than this. However in an environment subject to network snooping this should be kept as short as realistically possible.
Parameters:
timeout - the integer value to which timeout should be set.

getTimeout

public int getTimeout()
Get the maximum expected transmission time for response messages, in milliseconds. See setTimeout for details.
Returns:
the integer value representing the timeout in milliseconds

setMaxSkew

public void setMaxSkew(int maxSkew)
Set the maximum expected difference between the clock supplying the date parameter for validate and correct time, in milliseconds. The default is 0.5s. Given that exact clock synchronisation is near to impossible it should probably not be set significantly lower than this. In particular, at very low values there is likelyhood that even minor clock skew and/or rounding error will result in responses being rejected becasue the y appear to have been issued in the future.
Parameters:
maxSkew - the integer value of the maximum expected clock skew.

getMaxSkew

public int getMaxSkew()
Get the maximum expected clock skew. See setMaxSkew for details
Returns:
the integer value representing the maximum expected clock skew.

setKeyPrefix

public void setKeyPrefix(String keyPrefix)
Set the string prefix used to identify the relevant public key in the key store. Keys must be available in the key store under an alias formed from this prefix and the key-id carried in the response message being validated.
Parameters:
keyPrefix - the prefix string

getKeyPrefix

public String getKeyPrefix()
Get the maximum expected clock skew. See setKeyPrefix for details
Returns:
the prefix string