TIBCO EMS .NET API 8.5 TIBCO EMS .NET API 8.5

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Static Public Member Functions | Public Attributes | List of all members
TIBCO.EMS.EMSSSL Class Reference

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

## Static Public Member Functions
static void | Initialize ()
| Initializes SSL environment. More...
static void | SetAuthOnly (bool b)
| Enable or disable AUTH_ONLY on the client side for SSL 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 SSL 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 SSL 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 SSL property specifying if SSL 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 SSL 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 SSL 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 SSL 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 SSL 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 SSL 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"
| SSL Store type More...
const String | STORE_INFO = "TIBCO.EMS.ssl.store_info"
| SSL 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

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

Normally a client application obtains SSL 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 SSL 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 SSL protocol. Also sometimes it may be required or convenient to set ssl parameters globally that apply to all the connections. This class enables such requirements.

A EMS client is communicating with the server via SSL 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 an SSL connection, the server and the client application must set parameters in order for the SSL handshake to be successful. The server parameters are set by the administrator. Each client application is responsible for setting SSL parameters correctly in order to be able to establish SSL connection to the server.

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

- All SSL 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 SSL connection.
- SSL 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 SSL parameters, the SSL parameters set via calls to the methods of this class will be used.
- A client application can create a Map of SSL parameters and pass it directly into constructor of TopicConnectionFactory or QueueConnectionFactory.

SSL Parameters.

A client has to choose the certificate store it is going to work with before setting the SSL 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 an SSL 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 SSL handshake, the client can perform any specific validations in the host name verifier callback, returning false from this callback will cause the SSL handshake to terminate, return true will cause the SSL 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 | ( |  | ) |
| inline static

Get the value of the AUTH_ONLY flag

Returns
  True for enabled and false for disabled.

static StreamWriter TIBCO.EMS.EMSSSL.GetClientTracer | ( |  | ) |
| inline static

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

static EMSSSLHostNameVerifier TIBCO.EMS.EMSSSL.GetHostNameVerifier | ( |  | ) |
| inline static

Returns currently set custom host name verifier.

Returns
  Null if custom host name verifier is not set.

static String TIBCO.EMS.EMSSSL.GetTargetHostName | ( |  | ) |
| inline static

Returns the name set target host name.

static void TIBCO.EMS.EMSSSL.Initialize | ( |  | ) |
| inline static

Initializes SSL environment.

Normally SSL environment is initialized automatically when creating the first SSL connection. If SSL 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 | ) |
| inline static

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

For the client and server to use SSL 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 SSL 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 SSL only for authentication and switch to TCP protocol for all subsequent messaging. If `false` (default), then SSL is used for the lifetime of the connection.

See Also
  GetAuthOnly

GetAuthOnly

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

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 | ) |
| inline static

Set client tracer to given output stream.

Client tracing prints loaded certificates and information about the SSL 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 | ) |
| inline static

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 | ) |
| inline static

Set the target host name.

This is a required parameter for all .NET SSL 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 SSL property specifying if SSL 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 SSL 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 SSL 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 SSL 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 SSL 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"

SSL Store Info

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

SSL Store type

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

If server certificate has different name then SSL 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 SSL 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 SSL 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".