TLS specific class that provides methods, defines and other miscellaneous constants that are used to set TLS parameters that apply across all connections. More...

Static Public Member Functions
static void	Initialize ()
	Initializes TLS environment. More...

static void	SetAuthOnly (bool b)
	Enable or disable AUTH_ONLY on the client side for TLS connection. More...

static bool	GetAuthOnly ()
	Get the value of the AUTH_ONLY flag More...

static void	SetClientTracer (StreamWriter tracer)
	Set client tracer to given output stream. More...

static StreamWriter	GetClientTracer ()
	Returns the output target for the client tracer or null if client tracing is disabled. More...

static void	SetTargetHostName (String hostname)
	Set the target host name. More...

static String	GetTargetHostName ()
	Returns the name set target host name. More...

static void	SetHostNameVerifier (EMSSSLHostNameVerifier verifier)
	Set the custom host name verifier. More...

static EMSSSLHostNameVerifier	GetHostNameVerifier ()
	Returns currently set custom host name verifier. More...

static void	SetCertificateStoreType (EMSSSLStoreType type, Object storeInfo)
	Set the store type for all the connection factories More...

Public Attributes
const String	TRACE = "TIBCO.EMS.ssl.trace"
	Name of TLS property specifying if client trace is required. The value is a Boolean object. This name is defined as "TIBCO.EMS.ssl.trace". More...

const String	CLIENT_TRACER = "TIBCO.EMS.ssl.client_tracer"
	Name of TLS property specifying the client tracer object The is a valid tracer object This name is defined as "TIBCO.EMS.ssl.client_trace". More...

const String	AUTH_ONLY = "TIBCO.EMS.ssl.auth_only"
	Name of TLS property specifying if TLS is used for authentication only. The value is a Boolean object. This name is defined as "TIBCO.EMS.ssl.auth_only". More...

const String	TRUSTED_CERTIFICATES = "TIBCO.EMS.ssl.trusted_certs"
	Name of TLS property specifying the set of trusted certificates. The value is a Vector object, elements of the Vector can be: More...

const String	TARGET_HOST_NAME = "TIBCO.EMS.ssl.target_host_name"
	If server certificate has different name then TLS handshake fails. The value is a String object. This name is defined as "TIBCO.EMS.ssl.target_host_name". More...

const String	HOST_NAME_VERIFIER = "TIBCO.EMS.ssl.hostname_verifier"
	Name of TLS property specifying the custom host name verifier. Notice when this property is specified, the Map of parameters can not be stored in JNDI. The value is a EMSSSLHostNameVerifier object. This name is defined as "TIBCO.EMS.ssl.hostname_verifier". More...

const String	IDENTITY = "TIBCO.EMS.ssl.identity"
	Name of TLS property specifying the client-side identity. An identity usually consists of the certificate, corresponding private key and optionally a set of issuer certificates. The value specified by this property can be a certificate, a PKCS12 file or a KeyStore object. The last two object types normally include all elements of the identity into a single storage. In this case only PASSWORD property should be specified as the password required to decrypt the content of the specified identity data. If this property specifies the certificate file then PRIVATE_KEY must be also set and optionally ISSUER_CERTIFICATES. This name is defined as "TIBCO.EMS.ssl.identity". More...

const String	PASSWORD = "TIBCO.EMS.ssl.password"
	Name of TLS property specifying the password for the private key or the identity store. This name is defined as "TIBCO.EMS.ssl.password". More...

const String	CERT_NAME = "TIBCO.EMS.ssl.cert_name"
	Name of the certificate More...

const String	STORE_TYPE = "TIBCO.EMS.ssl.store_type"
	TLS Store type More...

const String	STORE_INFO = "TIBCO.EMS.ssl.store_info"
	TLS Store Info More...

const int	ENCODING_AUTO = 0x0000
	Integer defining AUTO format of the certificate or private key data. More...

const int	ENCODING_PEM = 0x0001
	Integer defining PEM format of the certificate or private key data. More...

const int	ENCODING_DER = 0x0002
	Integer defining DER format of the certificate or private key data. More...

const int	ENCODING_PKCS7 = 0x0010
	Integer defining PKCS7 format. More...

const int	ENCODING_PKCS8 = 0x0020
	Integer defining PKCS8 format of the private key data. More...

const int	ENCODING_PKCS12 = 0x0040
	Integer defining PKCS12 format of the client identity data. More...

const int	ENCODING_PFX = 0x0100
	Integer defining Pfx format of the client identity data. More...

Detailed Description

TLS specific class that provides methods, defines and other miscellaneous constants that are used to set TLS parameters that apply across all connections.

Normally a client application obtains TLS setup as a part of the ConnectionFactory definition. ConnectionFactory is usually obtained by the client applications via JNDI lookup calls. However, in some cases it may be more convenient or required to define TLS parameters locally in the client rather than as a result of JNDI lookup operation. This may be necessary, for example, due to security considerations when JNDI lookup operation can not be performed securely over TLS protocol. Also sometimes it may be required or convenient to set TLS parameters globally that apply to all the connections. This class enables such requirements.

A EMS client is communicating with the server via TLS protocol when the server URL provided to the ConnectionFactory is specified in the form ssl://host:port.

When the connection between the client and the server is a TLS connection, the server and the client application must set parameters in order for the TLS handshake to be successful. The server parameters are set by the administrator. Each client application is responsible for setting TLS parameters correctly in order to be able to establish TLS connection to the server.

Setting up TLS parameters by the client can be done in one of three ways:

All TLS parameters are specified in the ConnectionFactory, that factory is obtained by the client via a JNDI lookup call. Notice this does not address an issue of making JNDI lookup calls over TLS connection.
TLS parameters are set globally via calls to this class. When a ConnectionFactory is using a URL specifying 'ssl' protocol but does not specify any other TLS parameters, the TLS parameters set via calls to the methods of this class will be used.
A client application can create a Map of TLS parameters and pass it directly into constructor of TopicConnectionFactory or QueueConnectionFactory.

TLS Parameters.

A client has to choose the certificate store it is going to work with before setting the TLS parameters. EMS .NET client supports two different certificate stores and each store has different API please see EMSSSLFileStoreInfo and EMSSSLSystemStoreInfo for more information on the certificate store specific API's.

Cipher Suites.

Since the .NET framework does not allow to specify the ciphers from the client side, The EMS .NET api also does not have any provision of specifiying the ciphers.

General Setup

When a EMS .NET client establishes a TLS connection to the EMS server, it should at the very least specify the TARGET_HOST_NAME parameter, this is a required parameter for the SSLStream. A client then has to specify one of the certificate store types: EMSSSLStoreType.EMSSSL_STORE_TYPE_FILE or EMSSSLStoreType.EMSSSL_STORE_TYPE_SYSTEM along with the STORE_INFO object. The Store info has all the required information:

In case of the system store, the store info has information about the location of the store, the store name and the certificate name to look for in the store.
In case of the file store, the store info has information about the the client identity, the password for the private key and any optional trusted certs.

The client can set the host name verifier callback that will be called during the TLS handshake, the client can perform any specific validations in the host name verifier callback, returning false from this callback will cause the TLS handshake to terminate, return true will cause the TLS handshake to proceed.

If the client is interested in authentication only, then it needs call SetAuthOnly with a true flag. Normal behavior is to perform authentication and then any data that is sent/received encrypted/decrypted. Setting auth only to true will on both the client and the server will cause the client to perform authentication only and switch over to tcp connection for better performance at the expense of data security.

Member Function Documentation

static bool TIBCO.EMS.EMSSSL.GetAuthOnly ( )

inlinestatic

Get the value of the AUTH_ONLY flag

Returns: True for enabled and false for disabled.

static StreamWriter TIBCO.EMS.EMSSSL.GetClientTracer ( )

inlinestatic

Returns the output target for the client tracer or null if client tracing is disabled.

static EMSSSLHostNameVerifier TIBCO.EMS.EMSSSL.GetHostNameVerifier ( )

inlinestatic

Returns currently set custom host name verifier.

Returns: Null if custom host name verifier is not set.

static String TIBCO.EMS.EMSSSL.GetTargetHostName ( )

inlinestatic

Returns the name set target host name.

static void TIBCO.EMS.EMSSSL.Initialize ( )

inlinestatic

Initializes TLS environment.

Normally TLS environment is initialized automatically when creating the first TLS connection. If TLS environment has been already initialized this method does nothing.

Exceptions

SecurityException If method fails due to some error.

static void TIBCO.EMS.EMSSSL.SetAuthOnly ( bool b )

inlinestatic

Enable or disable AUTH_ONLY on the client side for TLS connection.

For the client and server to use TLS only during initial connection authentication, the ssl_auth_only parameter needs to be set on the server and AUTH_ONLY needs to be set by the client. Setting these flags on both the server and client side indicates that the TLS connection is only used to only perform authentication. Once authentication is complete, the client switches to a regular TCP connection to communicate with the server.

Connections use this setting at the time they are created. Changing this setting only affects connections created after the change.

Parameters

b	If set to `true`, then connections use TLS only for authentication and switch to TCP protocol for all subsequent messaging. If `false` (default), then TLS is used for the lifetime of the connection.

See also: GetAuthOnly

GetAuthOnly

static void TIBCO.EMS.EMSSSL.SetCertificateStoreType	(	EMSSSLStoreType	type,
		Object	storeInfo
	)

inlinestatic

Set the store type for all the connection factories

Parameters

storeInfo	If the store type is EMSSSL_STORE_TYPE_SYSTEM, then storeInfo must be an EMSSSLSystemStoreInfo object. If the store type is EMSSSL_STORE_TYPE_FILE, then storeInfo must be an EMSSSLFileStoreInfo object.
type	The type of certificate store. Can be either EMSSSL_STORE_TYPE_SYSTEM or EMSSSL_STORE_TYPE_FILE. See EMSSSLStoreType details.

static void TIBCO.EMS.EMSSSL.SetClientTracer ( StreamWriter tracer )

inlinestatic

Set client tracer to given output stream.

Client tracing prints loaded certificates and information about the TLS handshake errors and results.

Parameters

tracer The output stream to send the tracing information. Specify null as parameter to disable client tracing.

static void TIBCO.EMS.EMSSSL.SetHostNameVerifier ( EMSSSLHostNameVerifier verifier )

inlinestatic

Set the custom host name verifier.

Parameters

verifier Host name verifier. Set to null to remove custom host name verifier. See EMSSSLHostNameVerifier for details.

static void TIBCO.EMS.EMSSSL.SetTargetHostName ( String hostname )

inlinestatic

Set the target host name.

This is a required parameter for all .NET TLS connections. Because System.Net.Security.SslStream requires a target host, this value is required.

Parameters

hostname The name of the server as defined in the server's certificate. Usually the server's HostName is specified as the CN in the server's certificate. This value must match the name on the server's certificate server name.

Member Data Documentation

const String TIBCO.EMS.EMSSSL.AUTH_ONLY = "TIBCO.EMS.ssl.auth_only"

Name of TLS property specifying if TLS is used for authentication only. The value is a Boolean object. This name is defined as "TIBCO.EMS.ssl.auth_only".

const String TIBCO.EMS.EMSSSL.CERT_NAME = "TIBCO.EMS.ssl.cert_name"

Name of the certificate

const String TIBCO.EMS.EMSSSL.CLIENT_TRACER = "TIBCO.EMS.ssl.client_tracer"

Name of TLS property specifying the client tracer object The is a valid tracer object This name is defined as "TIBCO.EMS.ssl.client_trace".

const int TIBCO.EMS.EMSSSL.ENCODING_AUTO = 0x0000

Integer defining AUTO format of the certificate or private key data.

const int TIBCO.EMS.EMSSSL.ENCODING_DER = 0x0002

Integer defining DER format of the certificate or private key data.

const int TIBCO.EMS.EMSSSL.ENCODING_PEM = 0x0001

Integer defining PEM format of the certificate or private key data.

const int TIBCO.EMS.EMSSSL.ENCODING_PFX = 0x0100

Integer defining Pfx format of the client identity data.

const int TIBCO.EMS.EMSSSL.ENCODING_PKCS12 = 0x0040

Integer defining PKCS12 format of the client identity data.

const int TIBCO.EMS.EMSSSL.ENCODING_PKCS7 = 0x0010

Integer defining PKCS7 format.

const int TIBCO.EMS.EMSSSL.ENCODING_PKCS8 = 0x0020

Integer defining PKCS8 format of the private key data.

const String TIBCO.EMS.EMSSSL.HOST_NAME_VERIFIER = "TIBCO.EMS.ssl.hostname_verifier"

Name of TLS property specifying the custom host name verifier. Notice when this property is specified, the Map of parameters can not be stored in JNDI. The value is a EMSSSLHostNameVerifier object. This name is defined as "TIBCO.EMS.ssl.hostname_verifier".

const String TIBCO.EMS.EMSSSL.IDENTITY = "TIBCO.EMS.ssl.identity"

Name of TLS property specifying the client-side identity. An identity usually consists of the certificate, corresponding private key and optionally a set of issuer certificates. The value specified by this property can be a certificate, a PKCS12 file or a KeyStore object. The last two object types normally include all elements of the identity into a single storage. In this case only PASSWORD property should be specified as the password required to decrypt the content of the specified identity data. If this property specifies the certificate file then PRIVATE_KEY must be also set and optionally ISSUER_CERTIFICATES. This name is defined as "TIBCO.EMS.ssl.identity".

const String TIBCO.EMS.EMSSSL.PASSWORD = "TIBCO.EMS.ssl.password"

Name of TLS property specifying the password for the private key or the identity store. This name is defined as "TIBCO.EMS.ssl.password".

const String TIBCO.EMS.EMSSSL.STORE_INFO = "TIBCO.EMS.ssl.store_info"

TLS Store Info

const String TIBCO.EMS.EMSSSL.STORE_TYPE = "TIBCO.EMS.ssl.store_type"

TLS Store type

const String TIBCO.EMS.EMSSSL.TARGET_HOST_NAME = "TIBCO.EMS.ssl.target_host_name"

If server certificate has different name then TLS handshake fails. The value is a String object. This name is defined as "TIBCO.EMS.ssl.target_host_name".

const String TIBCO.EMS.EMSSSL.TRACE = "TIBCO.EMS.ssl.trace"

Name of TLS property specifying if client trace is required. The value is a Boolean object. This name is defined as "TIBCO.EMS.ssl.trace".

const String TIBCO.EMS.EMSSSL.TRUSTED_CERTIFICATES = "TIBCO.EMS.ssl.trusted_certs"

Name of TLS property specifying the set of trusted certificates. The value is a Vector object, elements of the Vector can be:

certificate object,
an Integer object specifying the certificate type followed by the certificate object. An Integer object before the object presenting the certificate data may be required when certificate data does not allow automatic detection of the encoding format. This name is defined as "TIBCO.EMS.ssl.trusted_certs".

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation