TIBCO Enterprise Message Service
com.tibco.tibjms

Class 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.

    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. In addition clients can also specify 'ALL' when specifying the cipher suites as a string to indicate that client is specifying all the available ciphers (In this case it's then up to EMS Server and client to negotiate on the cipher). 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
    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

      Fields 
      Modifier and Type Field and Description
      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 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
      This cipher is not supported, use "SSL authorization only" feature instead.
      static int SSL_RSA_WITH_NULL_SHA
      This cipher is not supported, use "SSL authorization only" feature instead.
      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

      Constructors 
      Constructor and Description
      TibjmsSSL() 
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      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 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 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
        This cipher is not supported, use "SSL authorization only" feature instead.
      • SSL_RSA_WITH_NULL_SHA

        public static final int SSL_RSA_WITH_NULL_SHA
        This cipher is not supported, use "SSL authorization only" feature instead.
      • 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
      • 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.
      • setSecureRandom

        public static void setSecureRandom(java.security.SecureRandom secureRandom)
        Set a java.Security.SecureRandom object.
      • 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.
      • addTrustedCerts

        public static void addTrustedCerts(java.lang.Object cert)
                                    throws JMSSecurityException
        Adds one or more trusted certificates to the set of trusted certificates. If a Java client uses TibjmsSSL.addTrustedCerts to add a certificate, the EMS server it communicates with must provide a certificate that can be directly authenticated by one of the client's trusted certificates. If the client's certificate chain lists an intermediary certificate between the provided and trusted certificates, the client will reject the connection.
        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.
      • 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

Copyright © TIBCO Software Inc. All rights reserved