net.grinder.script
Interface SSLControl

All Superinterfaces:

SSLContextFactory

public interface SSLControl
extends SSLContextFactory

Script control of SSL behaviour. This can be used to create SSL sockets or to set the appropriate client certificates to use. An implementation of this interface can be obtained using Grinder.ScriptContext.getSSLControl().

The Grinder provides specialised SSL support.

• By default, each run has its own SSL context so SSL sessions are not shared across threads or runs. Sharing sessions is not desirable because this would potentially allow a server under test to do less work. See setShareContextBetweenRuns(boolean).
• The Grinder trusts every server it talks to. It does not do any validation of server certificates or host names. To do so would make set up more onerous and place an unnecessary burden on The Grinder worker processes.
• The Grinder uses an insecure source of random information. This makes the SSL communication cryptographically less secure, but does not affect the processing necessary on any server it talks to. One benefit of this is faster start up times.

Do not use The Grinder to implement any SSL communication that you want to be secure.

This interface provides several methods for specifying the appropriate certificate and key pair to use for a thread:

• setKeyManagers(javax.net.ssl.KeyManager[])
• setKeyStore(InputStream, String)
• setKeyStoreFile(String, String)

Each of these methods creates a new SSL context when called. (They do not invalidate existing connections that use the previous context). Consequently you will want to call these methods before making connections for a particular run.

Author:

Philip Aston

Nested Class Summary

Nested classes/interfaces inherited from interface net.grinder.common.SSLContextFactory

SSLContextFactory.SSLContextFactoryException

Method Summary

boolean	getShareContextBetweenRuns() Get whether SSL contexts are shared between runs.
SSLContext	getSSLContext() Returns an appropriate JSSE SSLContext.
void	setKeyManagers(KeyManager[] keyManagers) Set the JSSE KeyManagers to use for the calling worker thread/run.
void	setKeyStore(InputStream keyStoreInputStream, String password) Overloaded version of setKeyStore for key stores of the default type (usually jks).
void	setKeyStore(InputStream keyStoreInputStream, String password, String keyStoreType) Set a key store to use for the calling worker thread/run.
void	setKeyStoreFile(String keyStoreFileName, String password) Overloaded version of setKeyStoreFile for key stores of the default type (usually jks).
void	setKeyStoreFile(String keyStoreFileName, String password, String keyStoreType) Set a key store to use for the calling worker thread/run.
void	setShareContextBetweenRuns(boolean b) Specify that there should be a single SSL context for a thread.

Method Detail

setKeyManagers

void setKeyManagers(KeyManager[] keyManagers)
                    throws InvalidContextException

Set the JSSE KeyManagers to use for the calling worker thread/run.

This will create a new SSL context. See the note above for details.

For compatibility with JSSE 1.0.X running under J2SE 1.3, The Grinder uses the X509KeyManager in the legacy JSSE com.sun.net.ssl package. This is slightly different to the X509KeyManager packaged in javax.net.ssl in J2SE 1.4 and later.

Parameters:

keyManagers - The key managers.

Throws:

InvalidContextException - If called from a non-worker thread.

See Also:

setKeyStore(InputStream, String, String), setKeyStoreFile(String, String)

setKeyStoreFile

void setKeyStoreFile(String keyStoreFileName,
                     String password,
                     String keyStoreType)
                     throws GeneralSecurityException,
                            InvalidContextException,
                            IOException

Set a key store to use for the calling worker thread/run. Convenient alternative to setKeyManagers(javax.net.ssl.KeyManager[]).

This will create a new SSL context. See the note above for details.

Parameters:

keyStoreFileName - Key store file name.

password - Key store password. Also used as the private key password.

keyStoreType - Key store type.

Throws:

GeneralSecurityException - If JSSE could not load the key store.

InvalidContextException - If called from a non-worker thread.

IOException - If key store could not be read.

See Also:

setKeyManagers(javax.net.ssl.KeyManager[]), setKeyStoreFile(String, String)

setKeyStoreFile

void setKeyStoreFile(String keyStoreFileName,
                     String password)
                     throws GeneralSecurityException,
                            InvalidContextException,
                            IOException

Overloaded version of setKeyStoreFile for key stores of the default type (usually jks).

Parameters:

keyStoreFileName - Key store file name.

password - Key store password. Also used as the private key password.

Throws:

GeneralSecurityException - If JSSE could not load the key store.

InvalidContextException - If called from a non-worker thread.

IOException - If key store could not be read.

See Also:

setKeyStoreFile(String, String, String)

setKeyStore

void setKeyStore(InputStream keyStoreInputStream,
                 String password,
                 String keyStoreType)
                 throws GeneralSecurityException,
                        InvalidContextException,
                        IOException

Set a key store to use for the calling worker thread/run. Convenient alternative to setKeyManagers(javax.net.ssl.KeyManager[]).

This will create a new SSL context. See the note above for details.

Parameters:

keyStoreInputStream - Input stream to key store.

password - Key store password. Also used as the private key password.

keyStoreType - Key store type.

Throws:

GeneralSecurityException - If JSSE could not load the key store.

InvalidContextException - If called from a non-worker thread.

IOException - If key store could not be read.

See Also:

setKeyManagers(javax.net.ssl.KeyManager[]), setKeyStoreFile(String, String)

setKeyStore

void setKeyStore(InputStream keyStoreInputStream,
                 String password)
                 throws GeneralSecurityException,
                        InvalidContextException,
                        IOException

Overloaded version of setKeyStore for key stores of the default type (usually jks).

Parameters:

keyStoreInputStream - Input stream to key store.

password - Key store password. Also used as the private key password.

Throws:

GeneralSecurityException - If JSSE could not load the key store.

InvalidContextException - If called from a non-worker thread.

IOException - If key store could not be read.

See Also:

setKeyStore(InputStream, String, String)

getSSLContext

SSLContext getSSLContext()
                         throws SSLContextFactory.SSLContextFactoryException

Returns an appropriate JSSE SSLContext. This can be used to obtain an SSLSocketFactory.

The Grinder optimises client SSL processing to increase the number of simultaneous client threads it is reasonable to run. It uses an insecure source of random information, and does not perform checks on the certificates presented by a server. Do not use The Grinder to implement any SSL communication that you want to be secure.

Specified by:

getSSLContext in interface SSLContextFactory

Returns:

The SSL context.

Throws:

SSLContextFactory.SSLContextFactoryException - If the SSLContext could not be found/created.

See Also:

SSLControl

getShareContextBetweenRuns

boolean getShareContextBetweenRuns()

Get whether SSL contexts are shared between runs.

Returns:

true => SSL contexts are per thread, false => SSL contexts are per run.

See Also:

setShareContextBetweenRuns(boolean)

setShareContextBetweenRuns

void setShareContextBetweenRuns(boolean b)

Specify that there should be a single SSL context for a thread. By default, a new SSL context is created per thread. This is a worker process level setting. If you call this, getSSLContext() will return the same context for every run.

If you use this method in conjunction with one of the setKey... methods you will want to guard the call to the setKey.. method so it is only called once per thread:

 grinder.SSLControl.shareContextBetweenRuns = 1

 class TestRunner:
   def __call__(self):
     if grinder.runNumber == 0:
       # First run.
       grinder.SSLControl.setKeyStoreFile("mykeystore.jks", "pass")

Alternatively, set the appropriate key store for the thread in the TestRunner constructor.

Parameters:

b - true => share SSL contexts between runs, false => each run should have a new SSL context.