com.novell.zos.tls
Class TlsConfiguration

java.lang.Object
  com.novell.zos.tls.TlsConfiguration

All Implemented Interfaces:

Serializable, Cloneable

public class TlsConfiguration
extends Object
implements Cloneable, Serializable

TLS Configuration Parameters for ZOS clients.

This class holds various TLS-related configuration parameters used by ZOS clients to connect to the server. By passing an instance of this class to the ZOS client API upon login, or by setting global defaults, the behavior and usage of Transport Layer Security (TLS) can be modified by client writers.

The factory default behavior for ZOS clients and agents is to enable TLS, with the level of encryption specified by the server upon client connection. By default, "client" (as opposed to "agent") connection mode is assumed.

This class is fully cloneable and serializable. It is recommended that the type-safe TlsConfiguration.copy() method be used for cloning.

The following is a simple example of the usage of this class to configure TLS support on a client connection to a ZOS server:

    import com.novell.zos.tls.TlsConfiguration;
    import com.novell.zos.grid.ClientAgent;
    import com.novell.zos.grid.Credential;
    import com.novell.zos.toolkit.CredentialFactory;
    ...
    TlsConfiguration tlsConfig = new TlsConfiguration();
    tlsConfig.setCertificatePath("/tmp");
    Credential cred = CredentialFactory.newPasswordCredential("user", "pass".toCharArray());
    ClientAgent client = ClientAgentFactory.newClientAgent("127.0.0.1");
    client.setTlsConfiguration(tlsConfig);
    client.login(cred);
    System.out.println("Logged In");

If custom handling of unknown or mismatched server certificates is required by the client, then add a call to TlsConfiguration.setCallbacks(TlsCallbacks) with an instance of TlsCallbacks providing methods for handling each of those cases.

If certain TLS parameters will always be the same for all instances (i.e. they were specified on a global command line at JVM launch) then those parameters can be specified as "global defaults" using the "setDefault*" versions of the various methods of this class. This may be used to avoid passing global configuration parameters among many different objects.

Since:

ZOS 1.3

See Also:

Serialized Form

Field Summary

static int	TLS_LEVEL_DISABLED TLS level indicating that TLS will not be used by the client.
static int	TLS_LEVEL_ENABLED TLS level indicating that TLS will be used by the client.
static int	TLS_LEVEL_SERVER TLS level indicating that TLS usage will be specified by the server.

Constructor Summary

TlsConfiguration()
Create a new TlsConfiguration instance with default parameters.

Method Summary

Object	clone() Implement the Cloneable interface.
TlsConfiguration	copy() Create a new clone of the current instance.
TlsCallbacks	getCallbacks() Get the global default callbacks.
String	getCertificateFile() Return the certificate file base name for this instance.
String	getCertificatePath() Return the certificate directory path for this instance.
long	getConnectionTimeout() Set the connection timeout for this instance.
static TlsCallbacks	getDefaultCallbacks() Get the global default callbacks.
static String	getDefaultCertificateFile() Return the global default certificate file base name.
static String	getDefaultCertificatePath() Get the global default TLS certificate directory.
static long	getDefaultConnectionTimeout() Return the global default connection timeout.
static int	getDefaultTlsLevel() Return the global default TLS configuration level.
static int	getDefaultTlsPort() Return the global default TCP port for TLS connections.
int	getTlsLevel() Return the TLS configuration level for this instance.
int	getTlsPort() Return the TCP port to use for connections established via this instance.
boolean	isAgentMode() Return the agent mode flag for this instance.
static boolean	isDefaultAgentMode() Return the global default agent mode.
static boolean	isDefaultTlsAware() Returns the global default "TLS Aware" flag.
boolean	isTlsAware() Return the "TLS Aware" flag for this instance.
void	setAgentMode(boolean mode) Set the agent mode flag for this instance.
void	setCallbacks(TlsCallbacks callbacks) Set the global default callbacks.
void	setCertificateFile(String filename) Set the certificate file base name for this instance.
void	setCertificatePath(String pathname) Set the certificate directory path for this instance.
void	setConnectionTimeout(long timeout) Set the connection timeout for this instance.
static void	setDefaultAgentMode(boolean mode) Set the global default agent mode.
static void	setDefaultCallbacks(TlsCallbacks callbacks) Set the global default callbacks.
static void	setDefaultCertificateFile(String filename) Set the global default certificate file base name.
static void	setDefaultCertificatePath(String pathname) Set the global default TLS certificate directory.
static void	setDefaultConnectionTimeout(long timeout) Set the global default connection timeout.
static void	setDefaultTlsAware(boolean aware) Set the global default "TLS Aware" flag.
static void	setDefaultTlsLevel(int level) Set the global default TLS configuration level.
static void	setDefaultTlsPort(int port) Set the global default TCP port for TLS connections.
void	setTlsAware(boolean aware) Set the "TLS Aware" flag for this instance.
void	setTlsLevel(int level) Set the TLS configuration level for this instance.
void	setTlsPort(int port) Set the TCP port to use for connections established via this instance.

Methods inherited from class java.lang.Object

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

Field Detail

TLS_LEVEL_DISABLED

public static final int TLS_LEVEL_DISABLED

TLS level indicating that TLS will not be used by the client.

See Also:

Constant Field Values

TLS_LEVEL_ENABLED

public static final int TLS_LEVEL_ENABLED

TLS level indicating that TLS will be used by the client.

See Also:

Constant Field Values

TLS_LEVEL_SERVER

public static final int TLS_LEVEL_SERVER

TLS level indicating that TLS usage will be specified by the server.

See Also:

Constant Field Values

Constructor Detail

TlsConfiguration

public TlsConfiguration()

Create a new TlsConfiguration instance with default parameters.

The new instance will be populated with the current global defaults.

Method Detail

copy

public TlsConfiguration copy()

Create a new clone of the current instance.

Returns a new TlsConfiguration instance containing the same parameter values as the current instance.

Returns:

A clone of the current instance.

clone

public Object clone()

Implement the Cloneable interface.

Calls the TlsConfiguration.copy() method and returns the cloned copy as an Object instance. The preferred method to clone an instance is to call TlsConfiguration.copy(), since it is type-safe.

Overrides:

clone in class Object

Returns:

A clone of the current instance.

setDefaultCallbacks

public static void setDefaultCallbacks(TlsCallbacks callbacks)

Set the global default callbacks.

Sets the TlsCallbacks instance to use by default for certificate callbacks. TlsConfiguration.setCallbacks(TlsCallbacks) overrides this value on a per-instance basis.

If the callbacks instance is set to null, then no default callbacks are made on certificate exceptions.

Parameters:

callbacks - New global default callbacks instance.

getDefaultCallbacks

public static TlsCallbacks getDefaultCallbacks()

Get the global default callbacks.

Returns the TlsCallbacks instance used by default for certificate callbacks. TlsConfiguration.setCallbacks(TlsCallbacks) overrides this value on a per-instance basis.

If the callbacks instance is set to null, then no default callbacks are made on certificate exceptions.

Returns:

callbacks Current global default callbacks instance.

setCallbacks

public void setCallbacks(TlsCallbacks callbacks)

Set the global default callbacks.

Sets the TlsCallbacks instance to use by default for certificate callbacks. TlsConfiguration.setCallbacks(TlsCallbacks) overrides this value on a per-instance basis.

If the callbacks instance is set to null, then no default callbacks are made on certificate exceptions.

Parameters:

callbacks - New global default callbacks instance.

getCallbacks

public TlsCallbacks getCallbacks()

Get the global default callbacks.

Returns the TlsCallbacks instance used by default for certificate callbacks. TlsConfiguration.setCallbacks(TlsCallbacks) overrides this value on a per-instance basis.

If the callbacks instance is set to null, then no default callbacks are made on certificate exceptions.

Returns:

callbacks Current global default callbacks instance.

setDefaultCertificatePath

public static void setDefaultCertificatePath(String pathname)

Set the global default TLS certificate directory.

Sets the static global default certificate directory path to pathname. The specified directory becomes the default certificate path for all new TlsConfiguration instances created after this static method is called.

Parameters:

pathname - The new global default certificate directory path.

getDefaultCertificatePath

public static String getDefaultCertificatePath()

Get the global default TLS certificate directory.

Returns the static global default certificate directory path set via a previous call to TlsConfiguration.setDefaultCertificatePath(String). If a default path has not yet been set then this method returns null. The global default certificate path is assigned as the certificate path for all new instances of this class.

Returns:

The new global default certificate directory path.

setCertificatePath

public void setCertificatePath(String pathname)

Set the certificate directory path for this instance.

Sets the path name of the directory in which TLS certificates are found and stored. Filenames specified via the TlsConfiguration.setCertificateFile(String) method are relative to this path.

Parameters:

pathname - The certificate directory path for this instance.

getCertificatePath

public String getCertificatePath()

Return the certificate directory path for this instance.

Returns the path name of the directory in which TLS certificates are found and stored. Filenames specified via the TlsConfiguration.setCertificateFile(String) method are relative to this path.

If neither an instance certificate path nor a global default certificate path have been set, then this method returns null.

Returns:

The certificate directory path for this instance.

setDefaultCertificateFile

public static void setDefaultCertificateFile(String filename)

Set the global default certificate file base name.

Sets the default base name for certificate files. This base name will be set as the default certificate file base name for all new instances of TlsConfiguration created after the call to this method.

Parameters:

filename - The default basename for certificate files.

See Also:

TlsConfiguration.setCertificateFile(String), TlsConfiguration.getCertificateFile()

getDefaultCertificateFile

public static String getDefaultCertificateFile()

Return the global default certificate file base name.

Returns the default base name for certificate files. All new instances of TlsConfiguration use the base name returned by this method as the default certificate file base name.

Returns:

The default basename for certificate files.

See Also:

TlsConfiguration.setCertificateFile(String), TlsConfiguration.getCertificateFile()

setCertificateFile

public void setCertificateFile(String filename)

Set the certificate file base name for this instance.

Sets the base name of the server certificate file to use when establishing connections to the remote host. The full path to the certificate file may be obtained by concatenating the return value of TlsConfiguration.getCertificatePath() and TlsConfiguration.getCertificateFile().

Parameters:

filename - The new certificate base filename for this instance.

getCertificateFile

public String getCertificateFile()

Return the certificate file base name for this instance.

Returns the base name of the server certificate file to use when establishing connections to the remote host. The full path to the certificate file may be obtained by concatenating the return value of TlsConfiguration.getCertificatePath() and TlsConfiguration.getCertificateFile().

This method may return null if default or instance value of the certificate file name has yet been specified.

Returns:

The certificate base filename for this instance.

setDefaultTlsPort

public static void setDefaultTlsPort(int port)
                              throws IllegalArgumentException

Set the global default TCP port for TLS connections.

Sets the global port number to be used for all new instances of TlsConfiguration created after calling this method.

Parameters:

port - The global default TCP port number for TLS connections.

Throws:

IllegalArgumentException - Thrown if port is not a valid TCP/IP port number in the range [0..65535].

getDefaultTlsPort

public static int getDefaultTlsPort()

Return the global default TCP port for TLS connections.

Returns the global port number to be used for all new instances of TlsConfiguration.

Returns:

The global default TCP port number for TLS connections.

setTlsPort

public void setTlsPort(int port)
                throws IllegalArgumentException

Set the TCP port to use for connections established via this instance.

Sets the TCP to be used when establishing a new TLS socket using this TlsConfiguration instance.

Parameters:

port - The TCP port to use for connections established via this instance.

Throws:

IllegalArgumentException - Thrown if port is not a valid TCP/IP port number in the range [0..65535].

getTlsPort

public int getTlsPort()

Return the TCP port to use for connections established via this instance.

Returns the TCP to be used when establishing a new TLS socket using this TlsConfiguration instance.

Returns:

The TCP port to use for connections established via this instance.

setDefaultConnectionTimeout

public static void setDefaultConnectionTimeout(long timeout)

Set the global default connection timeout.

Sets the default connection timeout to use for all new instances of TlsConfiguration after the call to this method.

The connection timeout is used when creating a socket to place a hard limit on the time spent waiting for a connection to an unreachable remote host before aborting the connection attempt.

Parameters:

timeout - The global default connection timeout.

getDefaultConnectionTimeout

public static long getDefaultConnectionTimeout()

Return the global default connection timeout.

Returns the default connection timeout to use for all new instances of TlsConfiguration.

The connection timeout is used when creating a socket to place a hard limit on the time spent waiting for a connection to an unreachable remote host before aborting the connection attempt.

Returns:

The global default connection timeout.

setConnectionTimeout

public void setConnectionTimeout(long timeout)

Set the connection timeout for this instance.

Sets the socket connection timeout for this instance.

The connection timeout is used when creating a socket to place a hard limit on the time spent waiting for a connection to an unreachable remote host before aborting the connection attempt.

Parameters:

timeout - The connection timeout for this instance.

getConnectionTimeout

public long getConnectionTimeout()

Set the connection timeout for this instance.

Sets the socket connection timeout for this instance.

The connection timeout is used when creating a socket to place a hard limit on the time spent waiting for a connection to an unreachable remote host before aborting the connection attempt.

Returns:

The connection timeout for this instance.

setDefaultTlsLevel

public static void setDefaultTlsLevel(int level)
                               throws IllegalArgumentException

Set the global default TLS configuration level.

Sets the default TLS configuration level to use for all new instances of TlsConfiguration created after the call to this method.

The TLS configuration level is one of: TlsConfiguration.TLS_LEVEL_DISABLED, TlsConfiguration.TLS_LEVEL_ENABLED, or TlsConfiguration.TLS_LEVEL_SERVER.

Parameters:

level - The global default TLS configuration level.

Throws:

IllegalArgumentException - Thrown if an unknown value is supplied for level

getDefaultTlsLevel

public static int getDefaultTlsLevel()

Return the global default TLS configuration level.

Returns the default TLS configuration level to use for all new instances of TlsConfiguration.

The TLS configuration level is one of: TlsConfiguration.TLS_LEVEL_DISABLED, TlsConfiguration.TLS_LEVEL_ENABLED, or TlsConfiguration.TLS_LEVEL_SERVER.

Returns:

The global default TLS configuration level.

setTlsLevel

public void setTlsLevel(int level)
                 throws IllegalArgumentException

Set the TLS configuration level for this instance.

Sets the TLS configuration level for sockets established via this instance.

The TLS configuration level is one of: TlsConfiguration.TLS_LEVEL_DISABLED, TlsConfiguration.TLS_LEVEL_ENABLED, or TlsConfiguration.TLS_LEVEL_SERVER.

Parameters:

level - The TLS configuration level for this instance.

Throws:

IllegalArgumentException - Thrown if an unknown value is supplied for level

getTlsLevel

public int getTlsLevel()

Return the TLS configuration level for this instance.

Returns the TLS configuration level for sockets established via this instance.

The TLS configuration level is one of: TlsConfiguration.TLS_LEVEL_DISABLED, TlsConfiguration.TLS_LEVEL_ENABLED, or TlsConfiguration.TLS_LEVEL_SERVER.

Returns:

The TLS configuration level for this instance.

setDefaultTlsAware

public static void setDefaultTlsAware(boolean aware)

Set the global default "TLS Aware" flag.

Sets the global "TLS Aware" flag to be used by all new instances of TlsConfiguration after the call to this method.

This flag can be used to enable and/or disable TLS functionality while also preserving user-specified TLS configuration parameters.

Parameters:

aware - Boolean value which, if true, indicates that the client is "TLS Aware".

isDefaultTlsAware

public static boolean isDefaultTlsAware()

Returns the global default "TLS Aware" flag.

Returns the global "TLS Aware" flag to be used by all new instances of TlsConfiguration

.

This flag can be used to enable and/or disable TLS functionality while also preserving user-specified TLS configuration parameters.

Returns:

Boolean value which, if true, indicates that the client is "TLS Aware".

setTlsAware

public void setTlsAware(boolean aware)

Set the "TLS Aware" flag for this instance.

Sets the "TLS Aware" flag for this instance.

This flag can be used to enable and/or disable TLS functionality while also preserving user-specified TLS configuration parameters.

Parameters:

aware - If true, indicates that the client is "TLS Aware".

isTlsAware

public boolean isTlsAware()

Return the "TLS Aware" flag for this instance.

Returns the "TLS Aware" flag for this instance.

This flag can be used to enable and/or disable TLS functionality while also preserving user-specified TLS configuration parameters.

Returns:

If true, indicates that the client is "TLS Aware".

setDefaultAgentMode

public static void setDefaultAgentMode(boolean mode)

Set the global default agent mode.

Sets the global default agent mode to be used by all new instances of TlsConfiguration created after the call to this method.

The agent mode flag should only be set to true for the ZOS Agent. All other clients should use the default value of false to indicate ZOS "client mode".

Parameters:

mode - If true then the client is a ZOS node/agent.

isDefaultAgentMode

public static boolean isDefaultAgentMode()

Return the global default agent mode.

Returns the global default agent mode to be used by all new instances of TlsConfiguration

.

The agent mode flag should only be set to true for the ZOS Agent. All other clients should use the default value of false to indicate ZOS "client mode".

Returns:

If true then the client is a ZOS node/agent.

setAgentMode

public void setAgentMode(boolean mode)

Set the agent mode flag for this instance.

Sets agent mode flag for this instance to indicate whether the client is a normal ZOS client or an agent/node.

The agent mode flag should only be set to true for the ZOS Agent/Node. All other clients should use the default value of false to indicate ZOS "client mode".

Parameters:

mode - If true then the client is a ZOS node/agent.

isAgentMode

public boolean isAgentMode()

Return the agent mode flag for this instance.

Returns agent mode flag for this instance to indicate whether the client is a normal ZOS client or an agent/node.

The agent mode flag should only be set to true for the ZOS Agent/Node. All other clients should use the default value of false to indicate ZOS "client mode".

Returns:

If true then the client is a ZOS node/agent.