org.jboss.remoting.security
Class SSLSocketBuilder

java.lang.Object
  extended byorg.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


Copyright ? 1998-2005 JBoss Inc . All Rights Reserved.