TIBCO Enterprise Message Service
Version 4.3.0

com.tibco.tibjms
Class TibjmsSSL

java.lang.Object
  extended bycom.tibco.tibjms.TibjmsSSL

public class TibjmsSSL
extends java.lang.Object

Provides methods and defines properties and miscellaneous constants which are used to set parameters for SSL connections.

Normally a client JMS 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.

A JMS 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. One exception is when using TIBCO Enterprise Message Service JNDI lookups, in that case the provider URL should specify tibjmsnaming protocol and the SSL connection type is set via com.tibco.tibjms.naming.TibjmsContext.SECURITY_PROTOCOL environment property.

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 successfull. 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:
1. 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.
2. 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.
3. A client application can create a Map of SSL parameters and pass it directly into constructor of TibjmsTopicConnectionFactory or TibjmsQueueConnectionFactory.

Notice that when using native JNDI supported by TIBCO Enterprise Message Service, JNDI lookup calls can be also made securely over SSL protocol. See documentation of com.tibco.tibjms.naming.TibjmsContext class for more details.

SSL Vendors.

TIBCO Enterprise Message Service supports multiple SSL vendors. Currently it supports the JSSE vendor (JSSE is a Java Secure Socket Extension which is an add-on package for JDK 1.3.x and is included with JDK 1.4.0 and later) and the Entrust SSL vendor. The SSL vendor can be specified in the ConnectionFactory the client application loads via JNDI lookup call, or it can be set directly as a JNDI context or ConnectionFactory property. Currently valid values for the vendor specification is one of the followinig strings:

'j2se' - to specify Sun's JSSE SSL vendor.
'j2se-default' - to specify default JSSE SSL vendor. Sun and IBM JSSE providers are supported.
'entrust61' - to specify Entrust SSL vendor.

Sun's JSSE is included with TIBCO Enterprise Message Service distribution. Entrust libraries version 7.0 or later should be obtained and installed separately.
Notice that after the first SSL conection is initialized, SSL vendor specification can not be changed and is ignored for all subsequent connections created by the same application.

SSL Parameters.

When a client establishes SSL connection to the JMS server, it should either specify trusted server certificates or completely disable host verification. If neither is specified then SSL communication will fail.
Trusted server certificates are the certificates which were used to issue server certificate. More than one trusted certificate can be specified by the client. Alternatively a client can completely disable server certificate verification and will effectively trust any server. If the client specifies trusted certificates then it should also make sure the common name in the certificate sent by the server is same as the server host name, or the client can supply another name which the name in the certificate will be verified against. Alternatively the client can disable host name verification or supply a custom host name verifier program.
If the server requires clients to present certificates then the client must set the client-side certificate, private key and optionally issuer certificates before establishing the SSL connection to the server. The client can also specify its choice and/or preference of the cipher suites to be used and renegotiation parameters.

Certificates, Private Key and Identity formats.

There are a number of supported formats which can be used to represent the set of trusted certificates, client certificate, client private key and optionally extra issuer certificates. Also note that the client identity consisting of the certificate, private key and optionally extra issuer certificates can be included into a single data block using PKCS12, KeyStore or Entrust Store encodings.
The set of Trusted Certificates represents all trusted issuers of the server certificate. It must be specified by the client application unless the host certificate verification is completely disabled. Trusted Certificates can be present in PEM or DER formats or as a PKCS7 file. Client certificate can be present in PEM or DER format or be a part of PKCS12, KeyStore or Entrust Store data. Private key can be present as PKCS8 file or be a part of PKCS12, KeyStore or Entrust Store data. Issuer certificates can be present in PEM or DER format or be a part of PKCS12, KeyStore or Entrust Store data. Currently JSSE does not support PKCS8-encoded private keys thus the client identity when using "j2se" SSL vendor must be preset as either PKCS12 or KeyStore data.
When a certificate, private key or the store is passed to any method of this class or is set as the value of corresponding properties, the format of the data can be detected automatically or, if not, the format must be specified explicitly by the application. In all cases the data passed as byte[] or InputStream does not require format specification if it represents one or more certificates encoded in PEM or DER format.
The following data types are accepted:
1. java.lang.String. If a certificate, identity or a private key are specified as java.lang.String then the value must be the name of the file on disk. If the file name has one of the predefined extensions described below then it is not necessary to provide the type of the data in the file. If the filename does not end with one of the predefined extensions, the type parameter or the corresponding property must be present.
2. byte[]. Can be used to specify the certificate, the private key or the store data. If specified byte[] represents one or more certificates in PEM or DER format or a private key in PKCS8 format then the type is not required. If the specified byte[] contains serialized PKCS12, Java KeyStore or Entrust Store data then the type must be specified.
3. java.io.InputStream. Can represent one or more certificates in PEM or DER format, private key in PKCS8 format, serialized PKCS12, Java KeyStore or Entrust Store data. The encoding and the type requirements are the same as for byte[] data.
4. java.security.cert.X509Certificate. Can be used to present a trusted certificate, client certificate or issuer certificate.
5. java.security.cert.X509Certificate[]. Can be used to present a set of trusted certificates.
6. java.security.KeyStore. Can be used to present Java KeyStore object as client identity data. Normally the KeyStore object includes the client certificate, corresponding private key and optionally extra issuer certificates.
7. Vendor specific object. Can be used to present Entrust certificate object iaik.x509.X509Certificate as a certificate.

Standard File Name Extentions.

The file names are accepted as the name of a certificate or private key file in many SSL parameters for trusted certificates, client identity and other. When a file name is specified it should either end with one of the standard extensions defining the encoding of the file or the file encoding must be provided separately, for instance as a parameter to addTrustedCerts or as an Integer object in the Vector of trusted certificates set by TRUSTED_CERTIFICATES property. The standard extensions include: .pem (PEM), .der (DER), .p8 (PKCS8), .p12 (PKCS12), .p7b (PKCS7), .jks (Java KeyStore) and .epf (Entrust Store). Notice that depending on the usage and chosen SSL vendor not all formats may be supported in all cases.

Cipher Suites.

The cipher suites supported by JMS clients are defined by this class as int values. When a client application is required to change the priority of cipher suites, or only use selected cipher suites, it can do so by setting the list of cipher suites. The list of cipher suites can be presented as an array of int values or alternatively as a java.lang.String value containing the list of cipher suite names. When the String representation is used, the application can specify only cipher suites to add or remove and can also change the priority of the cipher suite. When the list of cipher suites is presented as array of int values, it must specify all cipher suites allowed by the application in the order of priority.
When a String with the list of names is used, each cipher suite name can be prepended with a special character:
'+' - add cipher suite to the list
'-' - remove cipher suite from the list
'<' - move the cipher suite to be the first in the list
'>' - move the cipher suite to be the last in the list

The accepted cipher suite names are the same as the constant names defined by this class. In addition OpenSSL names can be used as well as the short names used by TIBCO Enterprise Message Service in the configuration files. It is advised that the Java applications only use the full names as defined by this class:

SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_DES_40_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_DHE_RSA_EXPORT_WITH_DES_40_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_DSS_EXPORT_WITH_DES_40_CBC_SHA
since EMS 4.2.0
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_DHE_DSS_WITH_AES_128_CBC_SHA
TLS_DHE_DSS_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA



Field Summary
static java.lang.String AUTH_ONLY
          Name of SSL property specifying if SSL is used for authentication only.
static java.lang.String CIPHER_SUITES
          Name of SSL property specifying the set of cipher suites to be used by the SSL connection.
static java.lang.String DEBUG_TRACE
          Name of SSL property specifying if client debug trace is required.
static java.lang.String ENABLE_VERIFY_HOST
          Name of SSL property specifying if client should verify server certificate.
static java.lang.String ENABLE_VERIFY_HOST_NAME
          Name of SSL property specifying if client should verify the common name in the server certificate.
static int ENCODING_AUTO
          Integer defining AUTO format of the certificate or private key data.
static int ENCODING_DER
          Integer defining DER format of the certificate or private key data.
static int ENCODING_ENTRUST
          Integer defining Entrust Store format of the client identity data.
static int ENCODING_KEYSTORE
          Integer defining KeyStore format of the client identity data.
static int ENCODING_PEM
          Integer defining PEM format of the certificate or private key data.
static int ENCODING_PKCS12
          Integer defining PKCS12 format of the client identity data.
static int ENCODING_PKCS7
          Integer defining PKCS7 format.
static int ENCODING_PKCS8
          Integer defining PKCS8 format of the private key data.
static java.lang.String EXPECTED_HOST_NAME
          Name of SSL property specifying the common name in the server certificate.
static java.lang.String HOST_NAME_VERIFIER
          Name of SSL property specifying the custom host name verifier.
static java.lang.String IDENTITY
          Name of SSL property specifying the client-side identity.
static java.lang.String IDENTITY_ENCODING
          Name of SSL property specifying the encoding of the data presented by IDENTITY property.
static java.lang.String ISSUER_CERTIFICATES
          Name of SSL property specifying the additional issuer certificates for the client certificate.
static java.lang.String PASSWORD
          Name of SSL property specifying the password for the private key or the identity store.
static java.lang.String PRIVATE_KEY
          Name of SSL property specifying the private key for the client certificate.
static java.lang.String PRIVATE_KEY_ENCODING
          Name of SSL property specifying the encoding of the data presented by PRIVATE_KEY property.
static java.lang.String RENEGOTIATE_INTERVAL
          Deprecated. This property is no longer supported, and may be removed from future versions of EMS.
static java.lang.String RENEGOTIATE_SIZE
          Deprecated. This property is no longer supported, and may be removed from future versions of EMS.
static int SSL_DHE_DSS_EXPORT_WITH_DES_40_CBC_SHA
          Cipher Suite: Ephemeral Diffie-Hellman key signed with DSS, and 40-bit DES, using SHA1 hash algorithm.
static int SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
          Cipher Suite: Ephemeral Diffie-Hellman key signed with DSS, and 3 key triple-DES in EDE-CBC mode, and SHA1 hash algorithm.
static int SSL_DHE_DSS_WITH_DES_CBC_SHA
          Cipher Suite: Ephemeral Diffie-Hellman key signed with DSS, and 56-bit DES, using SHA1 hash algorithm.
static int SSL_DHE_RSA_EXPORT_WITH_DES_40_CBC_SHA
          Cipher Suite: Ephemeral Diffie-Hellman key signed with RSA, and 40-bit DES, using SHA1 hash algorithm.
static int SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
          Cipher Suite: Ephemeral Diffie-Hellman key signed with RSA, nand Triple-DES in EDE-CBC mode, and SHA1 hash algorithm.
static int SSL_DHE_RSA_WITH_DES_CBC_SHA
          Cipher Suite: Ephemeral Diffie-Hellman key signed with RSA, and 56-bit DES, using SHA1 hash algorithm.
static int SSL_RSA_EXPORT_WITH_DES_40_CBC_SHA
          Cipher Suite: RSA key, Exportable 40-bit DES in CBC mode with SHA hash algorithm
static int SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
          Cipher Suite: RSA key, Exportable 40-bit RC2 in CBC mode with MD5 hash algorithm
static int SSL_RSA_EXPORT_WITH_RC4_40_MD5
          Cipher Suite: RSA key, Exportable 40-bit RC4 with MD5 hash algorithm
static int SSL_RSA_WITH_3DES_EDE_CBC_SHA
          Cipher Suite: RSA key, Triple-DES in EDE-CBC mode with SHA
static int SSL_RSA_WITH_DES_CBC_SHA
          Cipher Suite: RSA key, 56-bit DES in CBC mode with SHA
static int SSL_RSA_WITH_NULL_MD5
          Cipher Suite: RSA, no encryption, MD5 hash.
static int SSL_RSA_WITH_NULL_SHA
          Cipher Suite: RSA, no encryption, SHA hash.
static int SSL_RSA_WITH_RC4_128_MD5
          Cipher Suite: RSA key, 128-bit RC4 with MD5 hash algorithm
static int SSL_RSA_WITH_RC4_128_SHA
          Cipher Suite: RSA key, 128-bit RC4 with SHA hash algorithm
static java.lang.String TRACE
          Name of SSL property specifying if client trace is required.
static java.lang.String TRUSTED_CERTIFICATES
          Name of SSL property specifying the set of trusted certificates.
static java.lang.String VENDOR
          Name of SSL property specifying the SSL vendor to be used.
 
Constructor Summary
TibjmsSSL()
           
 
Method Summary
static void addIssuerCerts(java.lang.Object cert)
          Adds one or more issuer certificates to the set of issuer certificates.
static void addIssuerCerts(java.lang.Object cert, int encoding)
          Adds one or more issuer certificates in the specified format to the set of issuer certificates.
static void addTrustedCerts(java.lang.Object cert)
          Adds one or more trusted certificates to the set of trusted certificates.
static void addTrustedCerts(java.lang.Object cert, int encoding)
          Adds one or more trusted certificates in the specified format to the set of trusted certificates.
static void clearIssuerCerts()
          Removes all previously set issuer certificates.
static void clearTrustedCerts()
          Removes all previously set trusted certificates.
static java.lang.String getCipherSuiteName(int cipherSuite)
          Returns the name of cipher suite with specified number.
static java.io.PrintStream getClientTracer()
          Returns client tracer or null if client tracing is disabled.
static boolean getDebugTraceEnabled()
          Returns if debug tracing is enabled.
static java.lang.String getExpectedHostName()
          Returns the name set as the expected name in the host certificate.
static TibjmsSSLHostNameVerifier getHostNameVerifier()
          Returns currently set custom host name verifier.
static long getRenegotiateInterval()
          Deprecated. This method is no longer supported, and may be removed from future versions of EMS.
static long getRenegotiateSize()
          Deprecated. This method is no longer supported, and may be removed from future versions of EMS.
static int[] getSupportedCipherSuites()
          Returns all supported cipher suites.
static java.lang.String getVendor()
          Returns a String with the name of currently used SSL vendor.
static boolean getVerifyHost()
          Returns if the host certificate verification is enabled.
static boolean getVerifyHostName()
          Returns if the verification of the host certificate name is enabled.
static void initialize()
          Initializes SSL environment.
static void initialize(java.lang.String vendorName)
          Initializes SSL environment with specified SSL vendor.
static boolean isAuthOnly()
          Returns true if SSL is used only during connection authentication, returns false otherwise.
static boolean isCipherSuiteSupported(int cipherSuite)
          Returns if the specified cipher suite is supported.
static void setAuthOnly(boolean b)
          Set client connections to use SSL only during initial connection authentication.
static void setCipherSuites(int[] cipherSuites)
          Set cipher suites to be used by SSL connections.
static void setCipherSuites(java.lang.String cipherSuites)
          Set cipher suites as a String specification.
static void setClientTracer(java.io.PrintStream tracer)
          Set client tracer to given output stream.
static void setDebugTraceEnabled(boolean enabled)
          Enables debug tracing.
static void setExpectedHostName(java.lang.String hostname)
          Set the name which is expected to be set in the host certificate.
static void setHostNameVerifier(TibjmsSSLHostNameVerifier verifier)
          Set the custom host name verifier.
static void setIdentity(java.lang.Object identity, char[] password)
          Set client identity object and password.
static void setIdentity(java.lang.Object identity, int encoding, char[] password)
          Set client identity object in the specified format and password.
static void setIdentity(java.lang.Object identity, int encoding, java.lang.Object key, char[] password)
          Set client identity object in the specified format, private key and password.
static void setIdentity(java.lang.Object identity, int identityEncoding, java.lang.Object key, int keyEncoding, char[] password)
          Set client identity object in the specified format, private key in the specified format and password.
static void setIdentity(java.lang.Object identity, java.lang.Object key, char[] password)
          Set client identity, private key and password.
static void setPassword(char[] password)
          Sets private key password.
static void setRenegotiateInterval(long milliseconds)
          Deprecated. This method is no longer supported, and may be removed from future versions of EMS.
static void setRenegotiateSize(long bytes)
          Deprecated. This method is no longer supported, and may be removed from future versions of EMS.
static void setSecureRandom(java.security.SecureRandom secureRandom)
          Set a java.Security.SecureRandom object.
static void setVendor(java.lang.String vendorName)
          Set SSL vendor to the specified vendor.
static void setVerifyHost(boolean enable)
          Set if the host certificate should be verified by the client.
static void setVerifyHostName(boolean enable)
          Set if the name in the host certificate should be verified or not.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SSL_RSA_EXPORT_WITH_RC4_40_MD5

public static final int SSL_RSA_EXPORT_WITH_RC4_40_MD5
Cipher Suite: RSA key, Exportable 40-bit RC4 with MD5 hash algorithm


SSL_RSA_WITH_RC4_128_MD5

public static final int SSL_RSA_WITH_RC4_128_MD5
Cipher Suite: RSA key, 128-bit RC4 with MD5 hash algorithm


SSL_RSA_WITH_RC4_128_SHA

public static final int SSL_RSA_WITH_RC4_128_SHA
Cipher Suite: RSA key, 128-bit RC4 with SHA hash algorithm


SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5

public static final int SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
Cipher Suite: RSA key, Exportable 40-bit RC2 in CBC mode with MD5 hash algorithm


SSL_RSA_EXPORT_WITH_DES_40_CBC_SHA

public static final int SSL_RSA_EXPORT_WITH_DES_40_CBC_SHA
Cipher Suite: RSA key, Exportable 40-bit DES in CBC mode with SHA hash algorithm


SSL_RSA_WITH_DES_CBC_SHA

public static final int SSL_RSA_WITH_DES_CBC_SHA
Cipher Suite: RSA key, 56-bit DES in CBC mode with SHA


SSL_RSA_WITH_3DES_EDE_CBC_SHA

public static final int SSL_RSA_WITH_3DES_EDE_CBC_SHA
Cipher Suite: RSA key, Triple-DES in EDE-CBC mode with SHA


SSL_DHE_DSS_EXPORT_WITH_DES_40_CBC_SHA

public static final int SSL_DHE_DSS_EXPORT_WITH_DES_40_CBC_SHA
Cipher Suite: Ephemeral Diffie-Hellman key signed with DSS, and 40-bit DES, using SHA1 hash algorithm.


SSL_DHE_DSS_WITH_DES_CBC_SHA

public static final int SSL_DHE_DSS_WITH_DES_CBC_SHA
Cipher Suite: Ephemeral Diffie-Hellman key signed with DSS, and 56-bit DES, using SHA1 hash algorithm.


SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA

public static final int SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
Cipher Suite: Ephemeral Diffie-Hellman key signed with DSS, and 3 key triple-DES in EDE-CBC mode, and SHA1 hash algorithm.


SSL_DHE_RSA_EXPORT_WITH_DES_40_CBC_SHA

public static final int SSL_DHE_RSA_EXPORT_WITH_DES_40_CBC_SHA
Cipher Suite: Ephemeral Diffie-Hellman key signed with RSA, and 40-bit DES, using SHA1 hash algorithm.


SSL_DHE_RSA_WITH_DES_CBC_SHA

public static final int SSL_DHE_RSA_WITH_DES_CBC_SHA
Cipher Suite: Ephemeral Diffie-Hellman key signed with RSA, and 56-bit DES, using SHA1 hash algorithm.


SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA

public static final int SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
Cipher Suite: Ephemeral Diffie-Hellman key signed with RSA, nand Triple-DES in EDE-CBC mode, and SHA1 hash algorithm.


SSL_RSA_WITH_NULL_MD5

public static final int SSL_RSA_WITH_NULL_MD5
Cipher Suite: RSA, no encryption, MD5 hash.


SSL_RSA_WITH_NULL_SHA

public static final int SSL_RSA_WITH_NULL_SHA
Cipher Suite: RSA, no encryption, SHA hash.


VENDOR

public static final java.lang.String VENDOR
Name of SSL property specifying the SSL vendor to be used. Valid values are strings "j2se" or "entrust6".

This name is defined as "com.tibco.tibjms.ssl.vendor".

See Also:
Constant Field Values

TRACE

public static final java.lang.String TRACE
Name of SSL property specifying if client trace is required. The value is a Boolean object.

This name is defined as "com.tibco.tibjms.ssl.trace".

See Also:
Constant Field Values

AUTH_ONLY

public static final java.lang.String 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 "com.tibco.tibjms.ssl.auth_only".

See Also:
Constant Field Values

DEBUG_TRACE

public static final java.lang.String DEBUG_TRACE
Name of SSL property specifying if client debug trace is required. This is only applicable when using "entrust6" SSL vendor. When using "j2se" vendor debug tracing can be enabled by setting system property:
-Djavax.net.debug=ssl,handshake,data,trustmanager
Notice that enabling debug tracing can generate very large output and should be used only for debugging. The value is a Boolean object.

This name is defined as "com.tibco.tibjms.ssl.debug_trace".

See Also:
Constant Field Values

TRUSTED_CERTIFICATES

public static final java.lang.String TRUSTED_CERTIFICATES
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 "com.tibco.tibjms.ssl.trusted_certs".

See Also:
Constant Field Values

ENABLE_VERIFY_HOST

public static final java.lang.String ENABLE_VERIFY_HOST
Name of SSL property specifying if client should verify server certificate. By default the client always verifies server certificate to be issued by one or more certificates specified by TRUSTED_CERTIFICATES parameter. If this property is set to false then the client does not perform server certificate verification.
The value is a Boolean object.

This name is defined as "com.tibco.tibjms.ssl.enable_verify_host".

See Also:
Constant Field Values

ENABLE_VERIFY_HOST_NAME

public static final java.lang.String ENABLE_VERIFY_HOST_NAME
Name of SSL property specifying if client should verify the common name in the server certificate. It is enabled by default, unless the host verification is disabled. By default, if the EXPECTED_HOST_NAME property is not specified, the client verifies the common name to be the same as the name of the connected host. If EXPECTED_HOST_NAME is set then it should be the name in the certificate. Alternatively the client can provide custom host name verifier or disable host name verification completely setting this property to false.
The value is a Boolean object.

This name is defined as "com.tibco.tibjms.ssl.enable_verify_hostname".

See Also:
Constant Field Values

EXPECTED_HOST_NAME

public static final java.lang.String EXPECTED_HOST_NAME
Name of SSL property specifying the common name in the server certificate. if server certificate has different name then SSL handshake fails.
The value is a String object.

This name is defined as "com.tibco.tibjms.ssl.expected_hostname".

See Also:
Constant Field Values

HOST_NAME_VERIFIER

public static final java.lang.String HOST_NAME_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 TibjmsSSLHostNameVerifier object.

This name is defined as "com.tibco.tibjms.ssl.hostname_verifier".

See Also:
Constant Field Values

IDENTITY

public static final java.lang.String 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, a KeyStore object or an Entrust Store. Last three 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 "com.tibco.tibjms.ssl.identity".

See Also:
Constant Field Values

IDENTITY_ENCODING

public static final java.lang.String IDENTITY_ENCODING
Name of SSL property specifying the encoding of the data presented by IDENTITY property. This should be used when the type of data presented in IDENTITY property can not be detected automatically. The value of this property should be set as the String specifying one of the standard format names (i.e. "PEM", "P12", etc.), or as an Integer or String object specifying one of ENCODING_xxx values as they are defined by this class.

This name is defined as "com.tibco.tibjms.ssl.identity_encoding".

See Also:
Constant Field Values

ISSUER_CERTIFICATES

public static final java.lang.String ISSUER_CERTIFICATES
Name of SSL property specifying the additional issuer certificates for the client certificate. This should only be used when the IDENTITY property specifies a certificate but not the PKCS12, KeyStore or Entrust Store objects.

This name is defined as "com.tibco.tibjms.ssl.issuer_certs".

See Also:
Constant Field Values

PRIVATE_KEY

public static final java.lang.String PRIVATE_KEY
Name of SSL property specifying the private key for the client certificate. This should only be used when the IDENTITY* property specifies a certificate but not the PKCS12, KeyStore or Entrust Store objects.

This name is defined as "com.tibco.tibjms.ssl.private_key".

See Also:
Constant Field Values

PRIVATE_KEY_ENCODING

public static final java.lang.String PRIVATE_KEY_ENCODING
Name of SSL property specifying the encoding of the data presented by PRIVATE_KEY property. This should be used when the type of data presented in PRIVATE_KEY property can not detected automatically The value of this property should be set as the String specifying one of the standard format names (i.e. "PEM", "P12", etc.), or as an Integer or String object specifying one of ENCODING_xxx values as they are defined by this class.

This name is defined as "com.tibco.tibjms.ssl.private_key_encoding".

See Also:
Constant Field Values

PASSWORD

public static final java.lang.String PASSWORD
Name of SSL property specifying the password for the private key or the identity store. The value is a java.lang.String object or char[].

This name is defined as "com.tibco.tibjms.ssl.password".

See Also:
Constant Field Values

RENEGOTIATE_SIZE

public static final java.lang.String RENEGOTIATE_SIZE
Deprecated. This property is no longer supported, and may be removed from future versions of EMS.

Name of SSL property specifying the renegotiation size in bytes. Renegotiation will be initiated when the connection has transferred the specified number of bytes in both directions. The minimum accepted value is 65536 (64 kilobytes). Setting renegotiation size to 0 disables renegotiation based on the data size. By default size-based renegotiation is disabled. If RENEGOTIATE_INTERVAL is also specified then renegotiation occurres when the first condition is met.
The value is an Integer or Long object.

This name is defined as "com.tibco.tibjms.ssl.renegotiate_size".

See Also:
Constant Field Values

RENEGOTIATE_INTERVAL

public static final java.lang.String RENEGOTIATE_INTERVAL
Deprecated. This property is no longer supported, and may be removed from future versions of EMS.

Name of SSL property specifying the renegotiation interval in milliseconds. Renegotiation will be initiated after specified interval has elapsed. The minimum accepted value is 15000 (15 seconds). Setting renegotiation interval to 0 disables time-based renegotiation. By default time-based renegotiation is disabled. If RENEGOTIATE_SIZE is also specified then renegotiation occures when the first condition is met.
The value is an Integer or Long object.

This name is defined as "com.tibco.tibjms.ssl.renegotiate_interval".

See Also:
Constant Field Values

CIPHER_SUITES

public static final java.lang.String CIPHER_SUITES
Name of SSL property specifying the set of cipher suites to be used by the SSL connection. The value can be either an array of int values specifying the cipher suites in the order of priority using the cipher suite constants defined by this class. Alternatively the value can be specified as a java.lang.String listing the cipher suites by name.
See description of this class for more details.

This name is defined as "com.tibco.tibjms.ssl.cipher_suites".

See Also:
Constant Field Values

ENCODING_AUTO

public static final int ENCODING_AUTO
Integer defining AUTO format of the certificate or private key data.

See Also:
Constant Field Values

ENCODING_PEM

public static final int ENCODING_PEM
Integer defining PEM format of the certificate or private key data.

See Also:
Constant Field Values

ENCODING_DER

public static final int ENCODING_DER
Integer defining DER format of the certificate or private key data.

See Also:
Constant Field Values

ENCODING_PKCS7

public static final int ENCODING_PKCS7
Integer defining PKCS7 format.

See Also:
Constant Field Values

ENCODING_PKCS8

public static final int ENCODING_PKCS8
Integer defining PKCS8 format of the private key data.

See Also:
Constant Field Values

ENCODING_PKCS12

public static final int ENCODING_PKCS12
Integer defining PKCS12 format of the client identity data.

See Also:
Constant Field Values

ENCODING_ENTRUST

public static final int ENCODING_ENTRUST
Integer defining Entrust Store format of the client identity data.

See Also:
Constant Field Values

ENCODING_KEYSTORE

public static final int ENCODING_KEYSTORE
Integer defining KeyStore format of the client identity data.

See Also:
Constant Field Values
Constructor Detail

TibjmsSSL

public TibjmsSSL()
Method Detail

getVendor

public static java.lang.String getVendor()
Returns a String with the name of currently used SSL vendor.


setVendor

public static void setVendor(java.lang.String vendorName)
                      throws JMSSecurityException
Set SSL vendor to the specified vendor. Parameter vendorName should be one of: 'j2se' or 'entrust6'. After SSL environment has been initialized the vendor can not be changed and calls to this methods are ignored.

Throws:
JMSSecurityException - if specified vendor is not supported.

initialize

public static void initialize()
                       throws JMSSecurityException
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.

Throws:
JMSSecurityException - if method fails due to some error.

initialize

public static void initialize(java.lang.String vendorName)
                       throws JMSSecurityException
Initializes SSL environment with specified SSL vendor. Normally SSL environment is initialized automatically when creating the first SSL connection. If SSL environment has been already initialized this method does nothing.

Throws:
JMSSecurityException - if specified vendor is not supported or if method fails due to some error.

setDebugTraceEnabled

public static void setDebugTraceEnabled(boolean enabled)
Enables debug tracing. When 'j2se' SSL vendor is used debug tracing should be enabled via javax.net.debug system property.


setAuthOnly

public static void setAuthOnly(boolean b)
Set client connections to use SSL only during initial connection authentication. If parameter is true then connections use SSL only for authentication and switch to TCP protocol for all subsequent messaging. If parameter is false then SSL is used for the lifetime of the connection, which is the default mode. Connections use this setting at the time they are created. Changing this setting only affects connection created after the change. By default this parameter is disabled.

Parameters:
b - - true to only use SSL for authentication, false to use SSL for the lifetime of the connections.

isAuthOnly

public static boolean isAuthOnly()
Returns true if SSL is used only during connection authentication, returns false otherwise.


getDebugTraceEnabled

public static boolean getDebugTraceEnabled()
Returns if debug tracing is enabled.


setClientTracer

public static void setClientTracer(java.io.PrintStream tracer)
Set client tracer to given output stream. Specify null as parameter to disable client tracing. Client tracing prints loaded certificates and information about the SSL handshake errors and results.


getClientTracer

public static java.io.PrintStream getClientTracer()
Returns client tracer or null if client tracing is disabled.


setRenegotiateSize

public static void setRenegotiateSize(long bytes)
Deprecated. This method is no longer supported, and may be removed from future versions of EMS.

Set renegotiation size in bytes. Setting size to 0 disables renegotiation based on the size of data. If the value is not 0 and less than allowed minimum of 65536, it is set to 65536.


getRenegotiateSize

public static long getRenegotiateSize()
Deprecated. This method is no longer supported, and may be removed from future versions of EMS.

Returns renegotiation size in bytes or 0 if renegotiation based on size is disabled.


setRenegotiateInterval

public static void setRenegotiateInterval(long milliseconds)
Deprecated. This method is no longer supported, and may be removed from future versions of EMS.

Set renegotiation interval in milliseconds. Setting it to 0 disables renegotiation based on time interval. If the value is not 0 and less than allowed minimum of 15000, it is set to 15000 (15 seconds).


setSecureRandom

public static void setSecureRandom(java.security.SecureRandom secureRandom)
Set a java.Security.SecureRandom object.


getRenegotiateInterval

public static long getRenegotiateInterval()
Deprecated. This method is no longer supported, and may be removed from future versions of EMS.

Returns renegotiation interval in milliseconds or 0 if renegotiation based on time interval is disabled.


getCipherSuiteName

public static java.lang.String getCipherSuiteName(int cipherSuite)
                                           throws JMSSecurityException
Returns the name of cipher suite with specified number.

Throws:
JMSSecurityException - if cipherSuite parameter does not specify a valid cipher suite number.

isCipherSuiteSupported

public static boolean isCipherSuiteSupported(int cipherSuite)
                                      throws JMSSecurityException
Returns if the specified cipher suite is supported.

Throws:
JMSSecurityException - if cipherSuite parameter does not specify a valid cipher suite number.

getSupportedCipherSuites

public static int[] getSupportedCipherSuites()
                                      throws JMSSecurityException
Returns all supported cipher suites.

Throws:
JMSSecurityException - if method fails due to some error.

setCipherSuites

public static void setCipherSuites(int[] cipherSuites)
                            throws JMSSecurityException
Set cipher suites to be used by SSL connections.

Throws:
JMSSecurityException - if method fails due to some error.

setCipherSuites

public static void setCipherSuites(java.lang.String cipherSuites)
                            throws JMSSecurityException
Set cipher suites as a String specification.

Throws:
JMSSecurityException - if method fails due to some error.

setVerifyHost

public static void setVerifyHost(boolean enable)
Set if the host certificate should be verified by the client. By default it is always enabled.


getVerifyHost

public static boolean getVerifyHost()
Returns if the host certificate verification is enabled. By default it is always enabled.


setExpectedHostName

public static void setExpectedHostName(java.lang.String hostname)
Set the name which is expected to be set in the host certificate. Name in the certificate is present in the CN field of the certificate subject. By default the expected certificate name is the name of the connected host.


getExpectedHostName

public static java.lang.String getExpectedHostName()
Returns the name set as the expected name in the host certificate.


setVerifyHostName

public static void setVerifyHostName(boolean enable)
Set if the name in the host certificate should be verified or not. By default this is always enabled.


getVerifyHostName

public static boolean getVerifyHostName()
Returns if the verification of the host certificate name is enabled. By default this is always enabled.


setHostNameVerifier

public static void setHostNameVerifier(TibjmsSSLHostNameVerifier verifier)
Set the custom host name verifier. Set to null to remove custom host name verifier.


getHostNameVerifier

public static TibjmsSSLHostNameVerifier getHostNameVerifier()
Returns currently set custom host name verifier. Returns null if custom host name verifier is not set.


clearTrustedCerts

public static void clearTrustedCerts()
                              throws JMSSecurityException
Removes all previously set trusted certificates.

Throws:
JMSSecurityException

addTrustedCerts

public static void addTrustedCerts(java.lang.Object cert)
                            throws JMSSecurityException
Adds one or more trusted certificates to the set of trusted certificates.

Throws:
JMSSecurityException - if certificate data is not valid or if method fails due to some error.

addTrustedCerts

public static void addTrustedCerts(java.lang.Object cert,
                                   int encoding)
                            throws JMSSecurityException
Adds one or more trusted certificates in the specified format to the set of trusted certificates.

Throws:
JMSSecurityException - if certificate data is not valid or if method fails due to some error.

clearIssuerCerts

public static void clearIssuerCerts()
                             throws JMSSecurityException
Removes all previously set issuer certificates.

Throws:
JMSSecurityException

addIssuerCerts

public static void addIssuerCerts(java.lang.Object cert)
                           throws JMSSecurityException
Adds one or more issuer certificates to the set of issuer certificates.

Throws:
JMSSecurityException - if certificate data is not valid or if method fails due to some error.

addIssuerCerts

public static void addIssuerCerts(java.lang.Object cert,
                                  int encoding)
                           throws JMSSecurityException
Adds one or more issuer certificates in the specified format to the set of issuer certificates.

Throws:
JMSSecurityException - if certificate data is not valid or if method fails due to some error.

setIdentity

public static void setIdentity(java.lang.Object identity,
                               char[] password)
                        throws JMSSecurityException
Set client identity object and password. Client identity must include the certificate, private key and optionally issuer certificates.

Throws:
JMSSecurityException - if identity data is not valid or if method fails due to some error.

setIdentity

public static void setIdentity(java.lang.Object identity,
                               java.lang.Object key,
                               char[] password)
                        throws JMSSecurityException
Set client identity, private key and password.

Throws:
JMSSecurityException - if identity or private key data is not valid or if method fails due to some error.

setIdentity

public static void setIdentity(java.lang.Object identity,
                               int encoding,
                               char[] password)
                        throws JMSSecurityException
Set client identity object in the specified format and password. Client identity must include the certificate, private key and optionally issuer certificates.

Throws:
JMSSecurityException - if identity data is not valid or if method fails due to some error.

setIdentity

public static void setIdentity(java.lang.Object identity,
                               int encoding,
                               java.lang.Object key,
                               char[] password)
                        throws JMSSecurityException
Set client identity object in the specified format, private key and password.

Throws:
JMSSecurityException - if identity or private key data is not valid or if method fails due to some error.

setIdentity

public static void setIdentity(java.lang.Object identity,
                               int identityEncoding,
                               java.lang.Object key,
                               int keyEncoding,
                               char[] password)
                        throws JMSSecurityException
Set client identity object in the specified format, private key in the specified format and password.

Throws:
JMSSecurityException - if identity or private key data is not valid or if method fails due to some error.

setPassword

public static void setPassword(char[] password)
Sets private key password.


TIBCO Enterprise Message Service
Version 4.3.0

Copyright © TIBCO Software Inc. All rights reserved