uk.ac.rl.esc.browser
Class Browser

java.lang.Object
  extended by uk.ac.rl.esc.browser.Browser

public class Browser
extends java.lang.Object

Provides a simple to use interface to a selection of Browser certificate stores. These include

In particular you need to have Java 1.5+ to be able to use this API (because we need the Sun PKCS11 module). Mac support for Firefox/Mozilla could easily be added if the JDK for Mac included this module (maybe in JDK 1.6?). Also support for other PKCS11 modules could be added to support smart cards, etc. but this has not been done because they are not browsers.

There is some strange issues with .so/.dlls which means that the Browser class will only let you choose which browser once in the life of a JVM (because the PKCS11 module/init settings cannot be changed). In applets this means that a new browser executable is needed, not just a reload of the page. This is because the JVM persists for the life of the brwoser.

The following gives an overview of how you would use this class:

   private static class PasswordPrompt implements Browser.PasswordCallback {
        public char [] prompt(String promptString) {
            return passwordDialogBox(promptString);
        }
    }

    private static GSSCredential chooseCert() throws IOException, IllegalArgumentException, IllegalStateException, GeneralSecurityException, GlobusCredentialException, GSSException {
        String profile = Browser.getCurrentBrowser();
        if(profile==null) {
            String profiles[] = Browser.getBrowserList();
            if(profiles==null) return null; // there are no profiles!
            String choice = chooseDialog("Please choose browser to use:", profiles); //user chooses profile.
            Browser.setBrowser(choice); 
        }
        String dnList[]=null;
        try {
            dnList = Browser.getDNlist(new PasswordPrompt());
        } catch(javax.security.auth.login.FailedLoginException e) { 
            wrongPasswordDialog();
            return null;
        } 
        if(dnList==null) return null;  // No valid DNs found

        String dnChoice = chooseDialog("Please choose certificate to use:", dnList);
        return Browser.getGridProxy(dnChoice, type, lifetime, strength);
    } 


Nested Class Summary
static interface Browser.PasswordCallback
          A small interface which the Browser class uses to call back to the application to obtain passwords.
 
Method Summary
static java.lang.String[] getBrowserList()
          Searches for and returns all the browsers (and profiles) that it can understand.
static java.security.cert.X509Certificate getCertificate(java.lang.String DN)
          Returns the certificate is identified by the given DN.
static java.lang.String getCurrentBrowser()
          Returns the browser that operations on the Browser class will access.
static java.lang.String[] getDNlist(Browser.PasswordCallback unlockPass)
          Returns the list of (valid w.r.t time) DNs that can be accessed by the Browser module.
static org.ietf.jgss.GSSCredential getGridProxy(java.lang.String DN, int proxyType, int lifetimeHours)
          Create a Grid proxy certificate from the certificate (and private key) which is identified by the given DN.
static org.ietf.jgss.GSSCredential getGridProxy(java.lang.String DN, int proxyType, int lifetimeHours, int proxyStrength)
          Create a Grid proxy certificate from the certificate (and private key) which is identified by the given DN.
static byte[] getPKCS12Bundle(java.lang.String DN, char[] exportPassword)
          Returns a PKCS12 bundle comprising of the certificate and private key which is identified by the given DN, encrypted with the given password.
static void importPKCS12Bundle(byte[] pkcs12, char[] importPassword)
          Imports a PKCS12 bundle comprising of the certificate and private key, encrypted with the given password, into the user's browser.
static void setBrowser(java.lang.String browser)
          Sets the browser that operations on the Browser class will access.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getBrowserList

public static java.lang.String[] getBrowserList()
                                         throws java.io.IOException,
                                                java.lang.IllegalStateException
Searches for and returns all the browsers (and profiles) that it can understand. If you have already called setBrowser() within the lifetime of a JVM then will throw an IllegalStateException. Check if the browser has been set beforehand with getCurrentBrowser().

Returns:
List of browser names
Throws:
java.io.IOException
java.lang.IllegalStateException
See Also:
getCurrentBrowser()

setBrowser

public static void setBrowser(java.lang.String browser)
                       throws java.lang.IllegalStateException,
                              java.lang.IllegalArgumentException
Sets the browser that operations on the Browser class will access. It can only be called once within the lifetime of a JVM, IllegalStateException will be thrown if it has already been called. Also getBrowserList() must be called before this is called (otherwise IllegalStateException) will be thrown. If the browser given is not one of the browsers returned by getBrowserList() then IllegalArgumentException is thrown. If it returns null then a browser should be set with setBrowser() before any operations on the browser store is attempted. getBrowserList() can be used to get a list of browsers.

Parameters:
browser - the browser to be used (one of the names returned by getBrowserList())
Throws:
java.lang.IllegalStateException
java.lang.IllegalArgumentException
See Also:
getCurrentBrowser(), getBrowserList()

getDNlist

public static java.lang.String[] getDNlist(Browser.PasswordCallback unlockPass)
                                    throws java.lang.IllegalArgumentException,
                                           javax.security.auth.login.FailedLoginException,
                                           java.io.IOException,
                                           java.security.GeneralSecurityException
Returns the list of (valid w.r.t time) DNs that can be accessed by the Browser module. The browser to be used must have already been set by a call to setBrowser() (otherwise a IllegalArgumentException is thrown.

Parameters:
unlockPass - a call-back to obtain a password, this is used to log-in to a Mozilla/Firefox certifcate store.
Returns:
the DNs that are availiable in the current browser.
Throws:
javax.security.auth.login.FailedLoginException - If the Mozilla/Firefox password supplied by a user is incorrect
java.lang.IllegalArgumentException
java.io.IOException
java.security.GeneralSecurityException
See Also:
setBrowser(java.lang.String), Browser.PasswordCallback

getGridProxy

public static org.ietf.jgss.GSSCredential getGridProxy(java.lang.String DN,
                                                       int proxyType,
                                                       int lifetimeHours)
                                                throws java.io.IOException,
                                                       java.security.GeneralSecurityException,
                                                       java.lang.IllegalArgumentException,
                                                       java.lang.IllegalStateException,
                                                       org.globus.gsi.GlobusCredentialException,
                                                       org.ietf.jgss.GSSException
Create a Grid proxy certificate from the certificate (and private key) which is identified by the given DN. This must only be called after a call to getDNlist() and the DN given must be one of the DNs returned by getDNlist() otherwise a IllegalStateException or IllegalArgumentException, respectively, is thrown.

Parameters:
DN - one of the DNs returned by getDNlist().
proxyType - the type of proxy chosen from the constants in GSIConstants
lifetimeHours - the requested lifetime in hours of hte proxy certificate
Returns:
a Grid proxy certificate
Throws:
java.io.IOException
java.security.GeneralSecurityException
java.lang.IllegalArgumentException
java.lang.IllegalStateException
org.globus.gsi.GlobusCredentialException
org.ietf.jgss.GSSException
See Also:
getDNlist(uk.ac.rl.esc.browser.Browser.PasswordCallback)

getGridProxy

public static org.ietf.jgss.GSSCredential getGridProxy(java.lang.String DN,
                                                       int proxyType,
                                                       int lifetimeHours,
                                                       int proxyStrength)
                                                throws java.io.IOException,
                                                       java.security.GeneralSecurityException,
                                                       java.lang.IllegalArgumentException,
                                                       java.lang.IllegalStateException,
                                                       org.globus.gsi.GlobusCredentialException,
                                                       org.ietf.jgss.GSSException
Create a Grid proxy certificate from the certificate (and private key) which is identified by the given DN. This must only be called after a call to getDNlist() and the DN given must be one of the DNs returned by getDNlist() otherwise a IllegalStateException or IllegalArgumentException, respectively, is thrown.

Parameters:
DN - one of the DNs returned by getDNlist().
proxyType - the type of proxy chosen from the constants in GSIConstants
lifetimeHours - the requested lifetime in hours of hte proxy certificate
proxyStrength - the number of bits required in the proxy private key
Returns:
a Grid proxy certificate
Throws:
java.io.IOException
java.security.GeneralSecurityException
java.lang.IllegalArgumentException
java.lang.IllegalStateException
org.globus.gsi.GlobusCredentialException
org.ietf.jgss.GSSException
See Also:
getDNlist(uk.ac.rl.esc.browser.Browser.PasswordCallback)

getCertificate

public static java.security.cert.X509Certificate getCertificate(java.lang.String DN)
                                                         throws java.io.IOException,
                                                                java.security.GeneralSecurityException,
                                                                java.lang.IllegalArgumentException,
                                                                java.lang.IllegalStateException
Returns the certificate is identified by the given DN. This must only be called after a call to getDNlist() and the DN given must be one of the DNs returned by getDNlist() otherwise a IllegalStateException or IllegalArgumentException, respectively, is thrown.

Parameters:
DN - one of the DNs returned by getDNlist().
Returns:
the certificate
Throws:
java.io.IOException
java.security.GeneralSecurityException
java.lang.IllegalArgumentException
java.lang.IllegalStateException
See Also:
getDNlist(uk.ac.rl.esc.browser.Browser.PasswordCallback)

getPKCS12Bundle

public static byte[] getPKCS12Bundle(java.lang.String DN,
                                     char[] exportPassword)
                              throws java.io.IOException,
                                     java.security.GeneralSecurityException,
                                     java.lang.IllegalArgumentException,
                                     java.lang.IllegalStateException
Returns a PKCS12 bundle comprising of the certificate and private key which is identified by the given DN, encrypted with the given password. This must only be called after a call to getDNlist() and the DN given must be one of the DNs returned by getDNlist() otherwise a IllegalStateException or IllegalArgumentException, respectively, is thrown.

Parameters:
DN - one of the DNs returned by getDNlist().
exportPassword - the password to use to encrypt the PKCS12 bundle.
Returns:
a PKCS12 bundle (containing the key and certificate)
Throws:
java.io.IOException
java.security.GeneralSecurityException
java.lang.IllegalArgumentException
java.lang.IllegalStateException
See Also:
getDNlist(uk.ac.rl.esc.browser.Browser.PasswordCallback)

importPKCS12Bundle

public static void importPKCS12Bundle(byte[] pkcs12,
                                      char[] importPassword)
                               throws java.io.IOException,
                                      java.security.GeneralSecurityException,
                                      java.lang.IllegalArgumentException
Imports a PKCS12 bundle comprising of the certificate and private key, encrypted with the given password, into the user's browser. The browser to be used must have already been set by a call to setBrowser() (otherwise a IllegalArgumentException is thrown.

Parameters:
pkcs12 - a PKCS12 bundle (containing the key and certificate)
importPassword - the password used to encrypt the PKCS12 bundle.
Throws:
java.io.IOException
java.security.GeneralSecurityException
java.lang.IllegalArgumentException
See Also:
getDNlist(uk.ac.rl.esc.browser.Browser.PasswordCallback)

getCurrentBrowser

public static java.lang.String getCurrentBrowser()
Returns the browser that operations on the Browser class will access. If it returns null then a browser should be set with setBrowser() before any operations on the browser store is attempted. getBrowserList() can be used to get a list of browsers.

Returns:
the browser currently being used or null for none.
See Also:
setBrowser(java.lang.String), getBrowserList()