Creating Secure Sessions

Clients can optionally create secure Sessions that require trusted server certificates to establish a TLS/SSL-encrypted client connection to a PubSub+ event broker. When a secure Session is created, SMF information is transported using TLS/SSL over TCP instead of plain-text over TCP.

To create a secure Session, a number of TLS/SSL-specific Session properties must be specified as discussed below. In addition, the event broker that the secure Session will connect to must be properly configured, and the appropriate server certificate must be in place. For information on configuring an event broker to allow for secure connections, refer to TLS / SSL Service Configuration.

Related Samples

For an example of how to create and connect secure Sessions, refer to the SecureSession sample for the appropriate messaging API. Also, you can use secure Sessions on other samples by prepending “tcps:” to the hostname used in the sample (refer to Host).

TLS/SSL-Specific Properties

To create a secure Session, the following Session properties must configured.

The JavaScript API is configured through the browser where it runs, and doesn't support these configurations through Session properties.

TLS/SSL Secure Session Properties

Property Use Description

Host

C: SOLCLIENT_SESSION_PROP_HOST

C#/.NET: SessionProperties.Host

JCSMP: JCSMPProperties.HOST

Java RTO: SessionHandle.PROPERTIES.HOST

JavaScript: solace.SessionProperties.url

Node.js: solace.SessionProperties.url

Each host entry for a TLS/SSL connection requires an appropriate TLS/SSL protocol, and a specific TLS/SSL port number can optionally be specified.

If no port number is specified, the default port of 55443 is used.

For information on configuring hosts, refer to Host.

SSL Excluded Protocols

C: SOLCLIENT_SESSION_PROP_SSL_EXCLUDED_PROTOCOLS

C#/.NET: SessionProperties.SSLExcludedProtocols

JCSMP: JCSMPProperties.SSL_EXCLUDED_PROTOCOLS

Java RTO: SessionHandle.PROPERTIES.SSL_EXCLUDED_PROTOCOLS

JavaScript: N/A

Node.js: solace.SessionProperties.sslExcludedProtocols

A comma-separated list of encryption protocols that may not be used for secure connections. Possible values are:

  • SSLv3.0 (SSLv3)
  • TLS v1.0 (TLSv1)
  • TLS v1.1 (TLSv1.1)
  • TLS v1.2 (TLSv1.2)

See the preference for the specific values for SSL v3.0, TLS v1.0, TLS, v1.1, TLS V1.2. The default list is empty, meaning that any encryption protocol can be used (no protocols are excluded).

As of Solace PubSub+ 7.1, this property has replaced the deprecated property SSL Protocol. Solace recommends switching to the new property as soon as possible. You may not use SSL Exclude Protocols and SSL Protocol together.

SSL Certificate Validation

C: SOLCLIENT_SESSION_PROP_DEFAULT_SSL_VALIDATE_CERTIFICATE

C#/.NET: SessionProperties.SSLValidateCertificate

JCSMP: JCSMPProperties.SSL_VALIDATE_CERTIFICATE

Java RTO: SessionHandle.PROPERTIES.SSL_VALIDATE_CERTIFICATE

JavaScript: N/A

Node.js: solace.SessionProperties.sslValidateCertificate

Indicates that whether the API should validate server certificates with the trusted certificates in the trust store.

The API-specific information is as follows:

  • (C, Java RTO, Node.js, and .NET APIs) The trust store is a directory on a server that contains the trusted certificates. The default value for this property is True.
  • (JCSMP) A JKS or PKCS12 certificate file is used for the trust store.

SSL Certificate Date Validation

C: SOLCLIENT_SESSION_PROP_DEFAULT_SSL_VALIDATE_CERTIFICATE_DATE

C#/.NET: SessionProperties.SSLValidateCertificateDate

JCSMP: JCSMPProperties.SSL_VALIDATE_CERTIFICATE_DATE

Java RTO: SessionHandle.PROPERTIES.SSL_VALIDATE_CERTIFICATE_DATE

JavaScript: N/A

Node.js: N/A

Indicates whether the Session connection should fail when an expired certificate or a certificate not yet in use is received. The default is True.

 

No certificate date validation is performed if the SSL Certificate Validation property is set to False.

 

SSL Certificate Host Validation (SSL Server Certificate Validation Using Subject-Alternative Name )

C: SOLCLIENT_SESSION_PROP_SSL_VALIDATE_CERTIFICATE_HOST

C#/.NET: SessionProperties.SSLValidateCertificateHost

JCSMP: JCSMPProperties.SSL_VALIDATE_CERTIFICATE_HOST

Java RTO: SessionHandle.PROPERTIES.SSL_VALIDATE_CERTIFICATE_HOST

JavaScript: N/A

Node.js: N/A

Indicates if the session connection validates the subject alternative name in the X.509 certificate. If the X.509 certificate does not contain the subject alternative name section, the Common Name in the Subject field of the X.509 certificate is verified against the HOST property. The default and recommended setting is True.

No certificate host validation is performed if the SSL Certificate Validation property is set to False.

 

SSL Cipher Suites

C: SOLCLIENT_SESSION_PROP_DEFAULT_SSL_CIPHER_SUITES

C#/.NET: SessionProperties.SSLCipherSuites

JCSMP: JCSMPProperties.SSL_CIPHER_SUITES

Java RTO: SessionHandle.PROPERTIES.SSL_CIPHER_SUITES

JavaScript: N/A

Node.js: solace.SessionProperties.sslCipherSuites

A comma-separated list of cipher suites, listed in order of importance, to use to negotiate 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.

For a listing of the supported cipher suites in order of preference, refer to PubSub+ Messaging APIs for the appropriate messaging API. By default, no cipher suites are listed, which indicates that all supported ciphers should be considered.

SSL Trusted Store Directory

C: SOLCLIENT_SESSION_PROP_SSL_TRUST_STORE_DIR

C#/.NET: SessionProperties.SSLTrustStoreDir

JCSMP: N/A

Java RTO: SessionHandle.PROPERTIES.SSL_TRUST_STORE_DIR

JavaScript: N/A

Node.js: N/A

 

The directory where trusted certificates are stored.

The API-specific information is as follows:

  • (Java RTO, C, and .NET APIs only) The network directory where the trusted certificates are stored.
  • For iOS applications, the OpenSSL trusted store directory must be included in the application’s bundle and the SOLCLIENT_SESSION_PROP_SSL_TRUST_STORE_DIR property set to the path of this directory. For an example, refer to the iOS SecureSession sample. For instructions on running the SecureSession sample for iOS, see the README file in the ex/certs directory in the location where the iOS API is installed.

SSL Trust Store (file-based)

C: N/A

C#/.NET: N/A

JCSMP: JCSMPProperties.SSL_TRUST_STORE

Java RTO: N/A

Javascript: N/A

Node.js: solace.SessionProperties.sslTrustStores

The trust store files to use. The API-specific information is as follows:

  • (JCSMP only) The trust store file (in URL or path format) to use. This property is mandatory if the SSL_VALIDATE_CERTIFICATE property is set to True.
  • (Node.js only) The trusted certificated files (in path format) to use. This property is mandatory if the sslValidateCertificateproperty is set to True.

SSL Trust Store (in-memory)

C: N/A

C#/.NET: SessionProperties.SSLTrustStore

JCSMP: JCSMPProperties.SSL_IN_MEMORY_TRUST_STORE

Java RTO: N/A

Javascript: N/A

Node.js: N/A

 

Indicates the trusted certificates that are available as in-memory trust store. The API-specific information is as follows:

  • (.NET API only) The trusted certificates (in X509CertificateCollection format) to use for in-memory usage. This property is mandatory if the SSLValidateCertificate property is set to True. This property cannot be used in conjunction with SSLTrustStoreDir property.
  • (JCSMP only) The in-memory store in a java.security.KeyStore format. The SSL_TRUST_STORE_PASSWORD property is not required when using this property . Only use SSL_TRUST_STORE or SSL_IN_MEMORY_TRUST_STORE. You cannot mix in-memory and file-based (for example, URLs or filepaths) usage for the SSL trust store property. It's important to remember when using in-memory trust store that the Keystore object is considered immutable after its passed the PubSub+ Messaging API for JCSMP.

SSL Trust Store Password

C:N/A

C#/.NET: N/A

JCSMP: SessionHandle.PROPERTIES.SSL_TRUST_STORE_PASSWORD 

Java RTO: N/A

Javascript: N/A

Node.js: N/A

Specifies the password of the trust store. The API-specific information is as follows:

  • (JCSMP only) The trust store password for the trust store provided for the SSL_TRUST_STORE_PASSWORD  property. This property is mandatory if the SSL_VALIDATE_CERTIFICATE property is set to True.

SSL Trust Store Format

C: N/A

C#/.NET: N/A

JCSMP: JCSMPProperties.SSL_TRUST_STORE_FORMAT 

Java RTO: N/A

Javascript: N/A

Node.js: N/A

Indicates the format used by the trust store provided for the SSL Trust Store property. The API-specific information is as follows:

  • (JCSMP only) Supported trust store formats are JKS (the default) and PKCS12.

SSL Connection Downgrade To

 

C: SOLCLIENT_SESSION_PROP_SSL_CONNECTION_DOWNGRADE_TO

C#/.NET: SessionProperties.SSLConnectionDowngradeTo

JCSMP: SessionHandle.PROPERTIES.SSL_CONNECTION_DOWNGRADE_TO

Java RTO: SessionHandle.PROPERTIESSSL_CONNECTION_DOWNGRADE_TO

Javascript: N/A

Node.js: solace.SessionProperties.sslConnectionDowngradeTo

Indicates that the SSL connection should be downgraded following client authentication.

 

Allowed transport protocols for SSL Connection Downgrade To property are: "PLAIN_TEXT". This property is optional.