org.jboss.remoting.security
Class SSLSocketBuilder

java.lang.Object
  org.jboss.remoting.security.SSLSocketBuilder

All Implemented Interfaces:

SSLSocketBuilderMBean

public class SSLSocketBuilder
extends java.lang.Object
implements SSLSocketBuilderMBean

This builds SSL server socket factories and SSL socket factories.

The main methods are createSSLServerSocketFactory() and createSSLSocketFactory(). By default, these methods will use SSLServerSocketFactory.getDefault() and SSLSocketFactory.getDefault() and will require the proper system properties to be set. To use a custom configuration, will need to set either the useSSLServerSocketFactory or useSSLSocketFactory properties to be false.

Some common errors seen are:

1. javax.net.ssl.SSLException: No available certificate corresponds to the SSL cipher suites which are enabled

The 'javax.net.ssl.keyStore' system property has not been set and are using the default SSLServerSocketFactory.

2. java.net.SocketException: Default SSL context init failed: Cannot recover key

The 'javax.net.ssl.keyStorePassword' system property has not been set and are using the default SSLServerSocketFactory.

3. java.io.IOException: Can not create SSL Server Socket Factory due to the url to the key store not being set.

The default SSLServerSocketFactory is NOT being used (so custom configuration for the server socket factory) and the key store url has not been set.

4. java.lang.IllegalArgumentException: password can't be null

The default SSLServerSocketFactory is NOT being used (so custom configuration for the server socket factory) and the key store password has not been set.

Author:

Tom Elrod

Field Summary

static java.lang.String	DEFAULT_KEY_MANAGEMENT_ALGORITHM Value is SunX509.
static java.lang.String	DEFAULT_KEY_STORE_TYPE Value is JKS
static java.lang.String	DEFAULT_SECURE_SOCKET_PROTOCOL Value is TLS (Transport Layer Security).

Constructor Summary

SSLSocketBuilder()

Method Summary

void	create() create the service, do expensive operations etc
javax.net.ServerSocketFactory	createSSLServerSocketFactory() Will create a SSLServerSocketFactory.
javax.net.SocketFactory	createSSLSocketFactory() Will create a SSLSocketFactory.
void	destroy() destroy the service, tear down
java.lang.String	getKeyManagementAlgorithm() The algorithm for the key manager factory.
java.lang.String	getKeyStoreType() The type to be used for the key store.
java.lang.String	getSecureSocketProtocol() The protocol for the SSLContext.
boolean	getUseSSLServerSocketFactory() Return whether SSLServerSocketFactory.getDefault() will be used or not.
boolean	getUseSSLSocketFactory() Return whether SSLSocketFactory.getDefault() will be used or not.
void	setKeyManagementAlgorithm(java.lang.String keyManagementAlgorithm) The algorithm for the key manager factory.
void	setKeyPassword(java.lang.String passphrase) Sets the password to use for the keys within the key store.
void	setKeyStorePassword(java.lang.String passphrase) Sets the password to use for the key store.
void	setKeyStoreType(java.lang.String keyStoreType) The type to be used for the key store.
void	setKeyStoreURL(java.lang.String storeURL) This is the url string to the key store to use.
void	setSecureSocketProtocol(java.lang.String secureSocketProtocol) The protocol for the SSLContext.
void	setTrustStoreURL(java.lang.String storeURL) This is the url string to the trust store to use.
void	setUseClientMode(boolean useClientMode) Determines whether factories returned by SSLSocketBuilder create Sockets/ServerSockets in client or server mode.
void	setUseSSLServerSocketFactory(boolean shouldUse) Will indicate if should use the SSLServerSocketFactory.getDefault() for getting the ServerSocketFactory to use (when calling createSSLServerSocketFactory()).
void	setUseSSLSocketFactory(boolean shouldUse) Will indicate if should use the SSLSocketFactory.getDefault() for getting the SocketFactory to use (when calling createSSLSocketFactory()).
void	start() start the service, create is already called
void	stop() stop the service

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SECURE_SOCKET_PROTOCOL

public static final java.lang.String DEFAULT_SECURE_SOCKET_PROTOCOL

Value is TLS (Transport Layer Security).

See Also:

Constant Field Values

DEFAULT_KEY_MANAGEMENT_ALGORITHM

public static final java.lang.String DEFAULT_KEY_MANAGEMENT_ALGORITHM

Value is SunX509.

See Also:

Constant Field Values

DEFAULT_KEY_STORE_TYPE

public static final java.lang.String DEFAULT_KEY_STORE_TYPE

Value is JKS

See Also:

Constant Field Values

Constructor Detail

SSLSocketBuilder

public SSLSocketBuilder()

Method Detail

setUseSSLServerSocketFactory

public void setUseSSLServerSocketFactory(boolean shouldUse)

Will indicate if should use the SSLServerSocketFactory.getDefault() for getting the ServerSocketFactory to use (when calling createSSLServerSocketFactory()). If true, will allow for setting key store location (via javax.net.ssl.keyStore system property) and setting of the key store password (via javax.net.ssl.keyStorePassword system property) and no other configuration is needed (none of the other setters will need to be called and are in fact ignored). If set to false, will allow the custom setting of secure socket protocol, key management algorithm, key store type, key store url, key store password, and key password.

The default value is true.

NOTE: If this is not explicitly set to false, no customizations can be made and the default implementation provided by the JVM vendor being used will be executed.

Specified by:

setUseSSLServerSocketFactory in interface SSLSocketBuilderMBean

Parameters:

shouldUse -

getUseSSLServerSocketFactory

public boolean getUseSSLServerSocketFactory()

Return whether SSLServerSocketFactory.getDefault() will be used or not. See setUseSSLServerSocketFactory() for more information on what this means.

Specified by:

getUseSSLServerSocketFactory in interface SSLSocketBuilderMBean

Returns:

setUseSSLSocketFactory

public void setUseSSLSocketFactory(boolean shouldUse)

Will indicate if should use the SSLSocketFactory.getDefault() for getting the SocketFactory to use (when calling createSSLSocketFactory()). If true, will allow for setting trust store location (via Djavax.net.ssl.trustStore system property) and no other configuration is needed (none of the other setters will need to be called and are in fact ignored). If set to false, will allow the custom setting of secure socket protocol, key management algorithm, key store type, ant trust store url.

The default value is true.

NOTE: If this is not explicitly set to false, no customizations can be made and the default implementation provided by the JVM vendor being used will be executed.

Specified by:

setUseSSLSocketFactory in interface SSLSocketBuilderMBean

Parameters:

shouldUse -

getUseSSLSocketFactory

public boolean getUseSSLSocketFactory()

Return whether SSLSocketFactory.getDefault() will be used or not. See setUseSSLSocketFactory() for more information on what this means.

Specified by:

getUseSSLSocketFactory in interface SSLSocketBuilderMBean

Returns:

getSecureSocketProtocol

public java.lang.String getSecureSocketProtocol()

The protocol for the SSLContext. Some acceptable values are TLS, SSL, and SSLv3. Defaults to DEFAULT_SECURE_SOCKET_PROTOCOL.

Specified by:

getSecureSocketProtocol in interface SSLSocketBuilderMBean

setSecureSocketProtocol

public void setSecureSocketProtocol(java.lang.String secureSocketProtocol)

The protocol for the SSLContext. Some acceptable values are TLS, SSL, and SSLv3. Defaults to DEFAULT_SECURE_SOCKET_PROTOCOL.

Specified by:

setSecureSocketProtocol in interface SSLSocketBuilderMBean

getKeyManagementAlgorithm

public java.lang.String getKeyManagementAlgorithm()

The algorithm for the key manager factory. Defaults to DEFAULT_KEY_MANAGEMENT_ALGORITHM.

Specified by:

getKeyManagementAlgorithm in interface SSLSocketBuilderMBean

setKeyManagementAlgorithm

public void setKeyManagementAlgorithm(java.lang.String keyManagementAlgorithm)

The algorithm for the key manager factory. Defaults to DEFAULT_KEY_MANAGEMENT_ALGORITHM.

Specified by:

setKeyManagementAlgorithm in interface SSLSocketBuilderMBean

getKeyStoreType

public java.lang.String getKeyStoreType()

The type to be used for the key store. Defaults to DEFAULT_KEY_STORE_TYPE. Some acceptable values are JKS (Java Keystore - Sun's keystore format), JCEKS (Java Cryptography Extension keystore - More secure version of JKS), and PKCS12 (Public-Key Cryptography Standards #12 keystore - RSA's Personal Information Exchange Syntax Standard). These are not case sensitive.

Specified by:

getKeyStoreType in interface SSLSocketBuilderMBean

setKeyStoreType

public void setKeyStoreType(java.lang.String keyStoreType)

The type to be used for the key store. Defaults to DEFAULT_KEY_STORE_TYPE. Some acceptable values are JKS (Java Keystore - Sun's keystore format), JCEKS (Java Cryptography Extension keystore - More secure version of JKS), and PKCS12 (Public-Key Cryptography Standards #12 keystore - RSA's Personal Information Exchange Syntax Standard). These are not case sensitive.

Specified by:

setKeyStoreType in interface SSLSocketBuilderMBean

setKeyStorePassword

public void setKeyStorePassword(java.lang.String passphrase)

Sets the password to use for the key store. This only needs to be set if setUseSSLServerSocketFactory() is set to false (otherwise will be ignored). The value passed will also be used for the key password if it is not explicitly set.

Specified by:

setKeyStorePassword in interface SSLSocketBuilderMBean

Parameters:

passphrase -

setKeyPassword

public void setKeyPassword(java.lang.String passphrase)

Sets the password to use for the keys within the key store. This only needs to be set if setUseSSLServerSocketFactory() is set to false (otherwise will be ignored). If this value is not set, but the key store password is, it will use that value for the key password.

Specified by:

setKeyPassword in interface SSLSocketBuilderMBean

Parameters:

passphrase -

setUseClientMode

public void setUseClientMode(boolean useClientMode)

Determines whether factories returned by SSLSocketBuilder create Sockets/ServerSockets in client or server mode.

Parameters:

useClientMode -

createSSLServerSocketFactory

public javax.net.ServerSocketFactory createSSLServerSocketFactory()
                                                           throws java.io.IOException,
                                                                  java.security.NoSuchAlgorithmException,
                                                                  java.security.KeyStoreException,
                                                                  java.security.cert.CertificateException,
                                                                  java.security.UnrecoverableKeyException,
                                                                  java.security.KeyManagementException

Will create a SSLServerSocketFactory. If the useSSLServerSocketFactory property is set to true (which is the default), it will use SSLServerSocketFactory.getDefault() to get the server socket factory. Otherwise, if property is false, will use all the other custom properties that have been set to create a custom server socket factory.

Specified by:

createSSLServerSocketFactory in interface SSLSocketBuilderMBean

Returns:

Throws:

java.io.IOException

java.security.NoSuchAlgorithmException

java.security.KeyStoreException

java.security.cert.CertificateException

java.security.UnrecoverableKeyException

java.security.KeyManagementException

createSSLSocketFactory

public javax.net.SocketFactory createSSLSocketFactory()
                                               throws java.io.IOException,
                                                      java.security.NoSuchAlgorithmException,
                                                      java.security.KeyStoreException,
                                                      java.security.cert.CertificateException,
                                                      java.security.KeyManagementException

Will create a SSLSocketFactory. If the useSSLSocketFactory property is set to true (which is the default), it will use SSLSocketFactory.getDefault() to get the socket factory. Otherwise, if property is false, will use all the other custom properties that have been set to create a custom server socket factory.

Specified by:

createSSLSocketFactory in interface SSLSocketBuilderMBean

Returns:

Throws:

java.io.IOException

java.security.NoSuchAlgorithmException

java.security.KeyStoreException

java.security.cert.CertificateException

java.security.KeyManagementException

setKeyStoreURL

public void setKeyStoreURL(java.lang.String storeURL)
                    throws java.io.IOException

This is the url string to the key store to use. If UseSSLServerSocketFactory is true, this will be ignored and will use the value set by the javax.net.ssl.keyStore system property. Otherwise, if UseSSLServerSocketFactory is false, this must be set.

Specified by:

setKeyStoreURL in interface SSLSocketBuilderMBean

Parameters:

storeURL -

Throws:

java.io.IOException

setTrustStoreURL

public void setTrustStoreURL(java.lang.String storeURL)
                      throws java.io.IOException

This is the url string to the trust store to use. If UseSSLSocketFactory is true, this will be ignored and will use the value set by the javax.net.ssl.trustStore system property. Otherwise, if UseSSLSocketFactory is false, this must be set.

Specified by:

setTrustStoreURL in interface SSLSocketBuilderMBean

Parameters:

storeURL -

Throws:

java.io.IOException

create

public void create()
            throws java.lang.Exception

create the service, do expensive operations etc

Specified by:

create in interface SSLSocketBuilderMBean

Throws:

java.lang.Exception

start

public void start()
           throws java.lang.Exception

start the service, create is already called

Specified by:

start in interface SSLSocketBuilderMBean

Throws:

java.lang.Exception

stop

public void stop()

stop the service

Specified by:

stop in interface SSLSocketBuilderMBean

destroy

public void destroy()

destroy the service, tear down

Specified by:

destroy in interface SSLSocketBuilderMBean