issrg.utils.ssl
Class UtilitySSL

java.lang.Object
  issrg.utils.ssl.UtilitySSL

public final class UtilitySSL
extends java.lang.Object

general ssl connection methods. to be used throughout PERMIS.

• loadKeyStore
• keyManagerFactory
• trustManagerFactory
• setupSSLContext
• keepPrincipal

Version:

2008.06.11

Author:

mfb4@kent.ac.uk

Method Summary

static int	keepPrincipal(java.security.KeyStore keyStore, java.security.Principal keepPrincipal) Strip out all by the given principal's PKC.
static javax.net.ssl.KeyManagerFactory	keyManagerFactory(java.security.KeyStore identityStore, char[] identityStorePassword, java.lang.String identityManagerFactoryService) convinenece overloaded method.
static javax.net.ssl.KeyManagerFactory	keyManagerFactory(java.security.KeyStore identityStore, char[] identityStorePassword, java.lang.String identityManagerFactoryService, java.lang.String identityManagerFactoryProvider) create a key manager factory.
static java.security.KeyStore	loadKeyStore(java.io.InputStream keyStoreInputStream, char[] keyStorePassword, java.lang.String keyStoreService) convinenece overloaded method.
static java.security.KeyStore	loadKeyStore(java.io.InputStream keyStoreInputStream, char[] keyStorePassword, java.lang.String keyStoreService, java.lang.String keyStoreProvider) load in a key store.
static java.security.KeyStore	loadKeyStore(java.lang.String fileName, char[] keyStorePassword, java.lang.String keyStoreService)
static javax.net.ssl.SSLContext	setupSSLContext(javax.net.ssl.KeyManagerFactory keyManagerFactory, javax.net.ssl.TrustManagerFactory trustManagerFactory, java.lang.String sslContextService, java.lang.String sslContextProvider, java.lang.String secureRandomNumberService, java.lang.String secureRandomNumberProvider) creates an SSLContext from the with key and trust managers.
static javax.net.ssl.TrustManagerFactory	trustManagerFactory(java.security.KeyStore trustStore, java.lang.String trustManagerFactoryService) convinenece overloaded method.
static javax.net.ssl.TrustManagerFactory	trustManagerFactory(java.security.KeyStore trustStore, java.lang.String trustManagerFactoryService, java.lang.String trustManagerFactoryProvider) create a trust manager factory.

Methods inherited from class java.lang.Object

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

Method Detail

loadKeyStore

public static final java.security.KeyStore loadKeyStore(java.io.InputStream keyStoreInputStream,
                                                        char[] keyStorePassword,
                                                        java.lang.String keyStoreService,
                                                        java.lang.String keyStoreProvider)
                                                 throws UtilitySSLException

load in a key store. from the provided input stream.

The input stream is then closed, by this method.

If a password is incorrect than a UtilitySSLPasswordException exception is thrown.

Note Java's implementation of PKCS#12 fails to return the correct cause exception of: UnrecoverableKeyException so incorrect password is difficult to detect !

Parameters:

keyStoreName - the key store file name

keyStorePassword - the key store password

keyStoreService - the type of service

keyStoreProvider - the provider of the service (This is optional and should be an empty String "" to specify any provider)

Returns:

a KeyStore containing the contence of the keyStoreInputStream

Throws:

UtilitySSLException - with an embeded cause exception of what went wrong.

UtilitySSLPasswordException - if the password was identified as being incorect (see above Note)

Since:

2008.01.23, 2008.06.11

loadKeyStore

public static final java.security.KeyStore loadKeyStore(java.io.InputStream keyStoreInputStream,
                                                        char[] keyStorePassword,
                                                        java.lang.String keyStoreService)
                                                 throws UtilitySSLException

convinenece overloaded method. because the keyStoreProvider is optional.

Throws:

UtilitySSLException

loadKeyStore

public static final java.security.KeyStore loadKeyStore(java.lang.String fileName,
                                                        char[] keyStorePassword,
                                                        java.lang.String keyStoreService)
                                                 throws UtilitySSLException

Throws:

UtilitySSLException

keyManagerFactory

public static final javax.net.ssl.KeyManagerFactory keyManagerFactory(java.security.KeyStore identityStore,
                                                                      char[] identityStorePassword,
                                                                      java.lang.String identityManagerFactoryService,
                                                                      java.lang.String identityManagerFactoryProvider)
                                                               throws UtilitySSLException

create a key manager factory. and initialise it with the identity key store (containing the private key and it's public key certificate chain).

Note: there is another form of initialisation (init method) which allowes the key store to be opened at the point of making the SSL connection. The choice of init method is providor specific. This other from is not implemented by Java's standard key manager factories, and is not implemented in this class (as of 2008.06.11).

Parameters:

identityStore - a KeyStore containing the private key

identityStorePassword - the KeyStore password (same used to access the KeyStore)

identityManagerFactoryService - type of key manager factory E.g. "NewSunX509"

identityManagerFactoryProvider - (This is optional and should be an empty String "" to specify any provider)

Returns:

a key-manager-factory containing the identity KeyStore

Throws:

UtilitySSLException - with an embeded cause exception of what went wrong.

Since:

2008.01.23, 2008.06.11

keyManagerFactory

public static final javax.net.ssl.KeyManagerFactory keyManagerFactory(java.security.KeyStore identityStore,
                                                                      char[] identityStorePassword,
                                                                      java.lang.String identityManagerFactoryService)
                                                               throws UtilitySSLException

convinenece overloaded method. because the identityManagerFactoryProvider is optional.

Throws:

UtilitySSLException

trustManagerFactory

public static final javax.net.ssl.TrustManagerFactory trustManagerFactory(java.security.KeyStore trustStore,
                                                                          java.lang.String trustManagerFactoryService,
                                                                          java.lang.String trustManagerFactoryProvider)
                                                                   throws UtilitySSLException

create a trust manager factory. and initialise it with the trust key store (containing the trusted public key certificate).

Parameters:

trustStore - the KeyStore containing the trusted PKC's

trustManagerFactoryService - the type of trust manager factory e.g. "SunX509"

trustManagerFactoryProvider - (This is optional and should be an empty String "" to specify any provider)

Returns:

a trust-manager-factory containing the trust KeyStore

Throws:

UtilitySSLException - with an embeded cause exception of what went wrong.

Since:

2008.01.28, 2008.06.11

trustManagerFactory

public static final javax.net.ssl.TrustManagerFactory trustManagerFactory(java.security.KeyStore trustStore,
                                                                          java.lang.String trustManagerFactoryService)
                                                                   throws UtilitySSLException

convinenece overloaded method. because the trustManagerFactoryProvider is optional.

Throws:

UtilitySSLException

setupSSLContext

public static final javax.net.ssl.SSLContext setupSSLContext(javax.net.ssl.KeyManagerFactory keyManagerFactory,
                                                             javax.net.ssl.TrustManagerFactory trustManagerFactory,
                                                             java.lang.String sslContextService,
                                                             java.lang.String sslContextProvider,
                                                             java.lang.String secureRandomNumberService,
                                                             java.lang.String secureRandomNumberProvider)
                                                      throws UtilitySSLException

creates an SSLContext from the with key and trust managers. taken form the key and trust manager factories.

Parameters:

keyManagerFactory - that contains the identity KeyStores

trustManagerFactory - that contains the trust KeyStores

sslContextService - the type of SSLContext

sslContextProvider - (This is optional and should be an empty String "" to specify any provider)

secureRandomNumberService - the type of Random Number Generator

secureRandomNumberProvider - (This is optional and should be an empty String "" to specify any provider)

Returns:

an SSL contect

Throws:

UtilitySSLException - with an embeded cause exception of what went wrong.

Since:

2008.01.28, 2008.06.11

keepPrincipal

public static final int keepPrincipal(java.security.KeyStore keyStore,
                                      java.security.Principal keepPrincipal)
                               throws UtilitySSLException

Strip out all by the given principal's PKC.

remove from the key store every entry except ones belonging to the given principal.

This applies to TrustedCertificateEntry (PKC's) and PrivateKeyEntry (private key and the PKC chain)

This method was written in order to remove all trusted PKC's from a trust store except the PERMIS SOA.

Parameters:

KeyStore -

keepPrincipal -

Returns:

the number of entries still in the KeyStore

Throws:

UtilitySSLException - with an embedded cause exception, that is thrown if this method failed to "delete" one of the unwanted entries.

Since:

2008.01.28, 2008.06.11