Data Connection Properties - SSL Related

The following is a summary of the SSL-related data connection properties. Depending on the properties have enabled (set to true), some may override other properties. For details, see the PubSub+ Messaging API for JMS documentation.

SSL Certificate Validation

Indicates whether the API should validate server certificates with the trusted certificates in the trust store. A JKS or PKCS12 certificate file is used for the trust store. This property must be set to true to use the SSL Certificate Host Validation and SSL Certificate Date Validation properties.

  • Supported by: Solace PubSub+ and higher
  • Type: Boolean
  • Format: [true|false]
  • Default: true

This property applies to both the JNDI and data connections.

SSL Certificate Validation Property
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_VALIDATE_CERTIFICATE, true);

JNDI Properties File

Solace_JMS_SSL_ValidateCertificate=false

SSL Certificate Date Validation

Indicates whether the Session connection should fail when an expired certificate or a certificate not yet in use is received. No date validation is performed (overriding this property) if SSL Certificate Validation is set to false.

  • Supported by: Solace PubSub+ 6.0 and higher
  • Type: Boolean
  • Format: [true|false]
  • Default: true

This property applies to both the JNDI and data connections.

SSL Certificate Date Validation Property
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_VALIDATE_CERTIFICATE_DATE, true);

JNDI Properties File

Solace_JMS_SSL_ValidateCertificateDate=true

SSL Certificate Host Validation

Indicates if the session connection verifies if the subject alternative name in the server's X.509 certificate matches the host specified the URL property. If the X.509 certificate does not contain a subject alternative name section, the Common Name in the Subject field is checked instead. This setting is set to True by default (the recommended setting). It's important to note that the SSL Certificate Validation property overrides this property, therefore, if SSL Certificate Validation is set to false, no SSL certificate host validation is performed.

  • Supported by: Solace PubSub+ 9.7 and higher
  • Type: Boolean
  • Format: [true|false]
  • Default: true

This property applies to both the JNDI and data connections.

As per RFC 2818 and RFC 5280, Solace does not recommend that you set this property to false. Setting the property to false means that Server Certificate Validation Using Subject-Alternative Name is not performed.

SSL Certificate Host Validation Property

Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_VALIDATE_CERTIFICATE_HOST, true);

JNDI Properties File

Solace_JMS_SSL_ValidateCertificateHost=true

SSL Cipher Suite

The TLS/ SSL cipher suites to use to negotiate a secure connection with the event broker.

A cipher suite is a combination of cryptographic parameters that define the security algorithms and key sizes used for authentication, key agreement, encryption, and integrity protection. Cipher suites can be specified using their JSSE name or OpenSSL name.

The Solace JMS API supports the following cipher suites (showing the JSSE name with the OpenSSL name in brackets):

  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (ECDHE-RSA-AES256-SHA384)

    This cipher suite requires Java 7 or higher and the installation of the JCE Unlimited Strength Jurisdiction Policy Files.

  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (ECDHE-RSA-AES256-SHA)

    This cipher suite requires Java 7 or higher and the installation of the JCE Unlimited Strength Jurisdiction Policy Files.

  • TLS_RSA_WITH_AES_256_CBC_SHA256 (AES256-SHA256)

    This cipher suite requires Java 7 or higher and the installation of the JCE Unlimited Strength Jurisdiction Policy Files.

  • TLS_RSA_WITH_AES_256_CBC_SHA (AES256-SHA)

    This cipher suite requires installation of the JCE Unlimited Strength Jurisdiction Policy Files.

  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA (ECDHE-RSA-DES-CBC3-SHA)

    This cipher suite requires Java 7 or higher.

  • SSL_RSA_WITH_3DES_EDE_CBC_SHA (DES-CBC3-SHA)
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (ECDHE-RSA-AES128-SHA)

    This cipher suite requires Java 7 or higher.

  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (ECDHE-RSA-AES128-SHA256)

    This cipher suite requires Java 7 or higher.

  • TLS_RSA_WITH_AES_128_CBC_SHA256 (AES128-SHA256)

    This cipher suite requires Java 7 or higher.

  • TLS_RSA_WITH_AES_128_CBC_SHA (AES128-SHA)

This property applies to both the JNDI and data connections.

  • Supported by: Solace PubSub+ 6.0 and higher
  • Type: String
  • Format: Comma-separated list of ciphers
  • Default: All supported ciphers

This property applies to both the JNDI and data connections.

SSL Cipher Suite Property
Property Source (in descending priority) Example

Initial Context

env.put(

SupportedProperty.SOLACE_JMS_SSL_CIPHER_SUITE, "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ");

JNDI Properties File

Solace_JMS_SSL_CipherSuites=SSL_RSA_WITH_RC4_128_SHA

SSL Connection Downgrade To

Sets the transport protocol that TLS/SSL connections will be downgraded to after client authentication. This property applies to both the JNDI and data connections.

  • Supported by: Solace PubSub+ 7.2 and higher
  • Type: String

  • Allowed values: "PLAIN_TEXT"

This property applies to both the JNDI and data connections.

SSL Connection Downgrade To Property
Property Source (in descending priority) Example

Initial Context

env.put( SupportedProperty.SOLACE_JMS_SSL_CONNECTION_DOWNGRADE_TO, “PLAIN_TEXT”);

JNDI Properties File

Solace_JMS_SSL_ConnectionDowngradeTo=PLAIN_TEXT

SSL Excluded Protocols

A comma-separated list of encryption protocols that should not be used. SSL v3.0 (sslv3), TLS v1.0 (tlsv1), TLS v1.1 (tlsv1.1) and TLS v1.2 (tlsv1.2) are valid entries. When specifying multiple protocols, the order is not important.

  • Supported by: Solace PubSub+ and higher
  • Type: String
  • Format: Comma-separated list of protocol names
  • Default: ""

TLS v1.1 (tlsv1.1) and TLS v1.2 (tlsv1.2) require Java 7 or greater.

This property applies to both the JNDI and data connections.

SSL Excluded Protocols Property
Property Source (in descending priority) Example

Initial Context

env.put(

SupportedProperty.SOLACE_JMS_SSL_EXCLUDED_PROTOCOLS, "tlsv1");

JNDI Properties File

Solace_JMS_SSL_ExcludedProtocols=tlsv1

SSL Internal Normalized Key Store Format

This property specifies the format of the internal normalized key store. It allows you to override the type of the internal normalized keystore used for processing the keys from the SSL Key Store if there are issues with the default format.

This property applies to both the JNDI and data connections.

  • Supported by: Solace PubSub+ 7.2.1 and higher
  • Type: String
  • Format: Typically one of the standard built-in formats, like “jks” or “pkcs12”
  • Default: “”. If not specified then the type of SSL Key Store is used.

SSL Key Store Format
Property Source (in descending priority) Example

Initial Context

env.put(

SupportedProperty.SOLACE_JMS_SSL_KEY_STORE_NORMALIZED_FORMAT, “pkcs12”);

JNDI Properties File

Solace_JMS_SSL_KeyStoreNormalizedFormat =pkcs12

System

System Property -Djavax.net.ssl.keyStoreNormalizedType=PKCS12

SSL Key Store

This property specifies the keystore to use in the URL or path format. The keystore holds the client’s private key and certificate required to authenticate a client during the TLS/SSL handshake. This property is required if the authentication scheme is client certificate authentication.

This property applies to both the JNDI and data connections.

  • Supported by: Solace PubSub+ 6.1 and higher
  • Type: String
  • Format: URL or path of the keystore file
  • Default: ""

This property applies to both the JNDI and data connections.

SSL Key Store Property
Property Source (in descending priority) Example

Initial Context

env.put(

SupportedProperty.SOLACE_JMS_SSL_KEY_STORE, "mykeystore.jks");

JNDI Properties File

Solace_JMS_SSL_KeyStore=myKeyStore.jks

System

-Djavax.net.ssl.keyStore=myKeyStore.jks

SSL Key Store Format

This property specifies the format of the given keystore. It applies to both the JNDI and data connections.

  • Supported by: Solace PubSub+ 6.1 and higher
  • Type: String
  • Format: JKS or PKCS12
  • Default: "jks"

This property applies to both the JNDI and data connections.

SSL Key Store Format
Property Source (in descending priority) Example

Initial Context

env.put(

SupportedProperty.SOLACE_JMS_SSL_KEY_STORE_FORMAT, "pkcs12");

JNDI Properties File

Solace_JMS_SSL_KeyStoreFormat=pkcs12

System

-Djavax.net.ssl.keyStoreType=PKCS12

SSL Key Store Password

This property specifies the keystore password to use and allows JMS to verify the integrity of the keystore.

This property applies to both the JNDI and data connections.

  • Supported by: Solace PubSub+ and higher
  • Type: String
  • Format: String
  • Default: ""

This property applies to both the JNDI and data connections.

SSL Key Store Password
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_KEY_STORE_PASSWORD, "password");

JNDI Properties File

Solace_JMS_SSL_KeyStoreFormat=mypass

System

-Djavax.net.ssl.keyStorePassword=mypass

SSL Private Key Alias

This property specifies which private key in the keystore to use for authentication. This property is necessary when a keystore with multiple private key entries is used.

This property applies to both the JNDI and data connections.

  • Supported by: Solace PubSub+ and higher
  • Type: String
  • Format: String
  • Default: ""

This property applies to both the JNDI and data connections.

SSL Private Key Alias
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_PRIVATE_KEY_ALIAS, "alias");

JNDI Properties File

Solace_JMS_SSL_PrivateKeyAlias=alias

SSL Private Key Password

This property specifies which private key in the keystore to use for authentication. This property is necessary when a keystore with multiple private key entries is used.

This property applies to both the JNDI and data connections.

  • Supported by: Solace PubSub+ 6.1 and higher
  • Type: String
  • Format: String
  • Default: ""

This property applies to both the JNDI and data connections.

SSL Private Key Password Property
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_PRIVATE_KEY_PASSWORD, "password");

JNDI Properties File

Solace_JMS_SSL_PrivateKeyPassword=password

SSL Protocol

A comma-separated list of the encryption protocols to use. SSL v3.0 (sslv3), TLS v1.0 (tlsv1), TLS v1.1 (tlsv1.1) and TLS v1.2 (tlsv1.2) are supported. When specifying multiple protocols, the order is not important.

  • Supported by: Solace PubSub+ 6.0 and higher
  • Type: String
  • Format: Comma-separated list of protocol names
  • Default: "sslv3,tlsv1,tlsv1.1,tlsv1.2".
  • As of Solace PubSub+ 7.1, use of the “SSL Excluded Protocols” property is recommended instead. You may not use both “SSL Protocol” and “SSL Excluded Protocols”. Refer to SSL Excluded Protocols.
    • TLS v1.1 (tlsv1.1) and TLS v1.2 (tlsv1.2) require Java 7 or greater.

This property applies to both the JNDI and data connections.

SSL Protocol Property
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_PROTOCOL, "tlsv1");

JNDI Properties File

Solace_JMS_SSL_Protocol=tlsv1

SSL Trust Store

The trust store file to use. This property is mandatory if the SSL Certificate Validation property is set to true.

  • Supported by: Solace PubSub+ 6.0 and higher
  • Type: String
  • Format: URL or path of the trust store file
  • Default: ""

This property applies to both the JNDI and data connections.

SSL Trust Store Property
Property Source (in descending priority) Example

System

-Djavax.net.ssl.trustStore=myTrustStore.jks

JNDI Properties File

Solace_JMS_SSL_TrustStore=myTrustStore.jks

Initial Context

env.put(

SupportedProperty.SOLACE_JMS_SSL_TRUST_STORE, "mytruststore.jks");

SSL Trust Store Format

Indicates the format used by the trust store provided for the SSL Trust Store property.

  • Supported by: Solace PubSub+ 6.0 and higher
  • Type: String
  • Format: "jks" or "pkcs12"
  • Default: "jks"

This property applies to both the JNDI and data connections.

SSL Trust Store Format Property
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_TRUST_STORE_FORMAT, "pkcs12");

JNDI Properties File

Solace_JMS_SSL_TrustStoreFormat=pkcs12

System

-Djavax.net.ssl.keyStoreType=PKCS12

SSL Trust Store Password

The password for the trust store provided for the SSL Trust Store property. This property is mandatory if the SSL Certificate Validation property is set to true.

  • Supported by: Solace PubSub+ 6.0 and higher
  • Type: String
  • Format: String
  • Default: ""

This property applies to both the JNDI and data connections.

SSL Trust Store Password Property
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_TRUST_STORE_PASSWORD, "password");

JNDI Properties File

Solace_JMS_SSL_TrustStorePassword=mypass

System

-Djavax.net.ssl.trustStorePassword=mypass

SSL Trusted Common Name List

A list of up to 16 acceptable common names for matching in server certificates. If no common names are provided (the default), it means that there is no common name verification and all common names are acceptable.

No common name validation is performed if SSL Certificate Validation is set to false or the SSL Server Certificate Validation is set to true.

  • Supported by: Solace PubSub+ 6.0 and higher
  • Type: String
  • Format: Comma-separated list of common names

    Leading and trailing white spaces are considered to be part of the common names and are not ignored.

  • Default: ""

This property applies to both the JNDI and data connections.

SSL Trusted Common Name List
Property Source (in descending priority) Example

Initial Context

env.put(SupportedProperty.SOLACE_JMS_SSL_TRUSTED_COMMON_NAME_LIST, "acme.com,www.acme.com");

JNDI Properties File

Solace_JMS_SSL_TrustedCommonNameList= acme.com,www.acme.com