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, see TLS / SSL Service Configuration.

Related Samples

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

TLS/SSL-Specific Properties

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

The PubSub+ 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	PubSub+ C API: `SOLCLIENT_SESSION_PROP_HOST` PubSub+ .NET API: `SessionProperties.Host` PubSub+ Java RTO API: `SessionHandle.PROPERTIES.HOST` PubSub+ JavaScript API: `solace.SessionProperties.url` PubSub+ Node.js API: `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, see Host.
Configuring Minimum and Maximum SSL Protocols	PubSub+ C API: `SOLCLIENT_SESSION_PROP_MINIMUM_TLS_PROTOCOL_VERSION` and `SOLCLIENT_SESSION_PROP_MAXIMUM_TLS_PROTOCOL_VERSION` PubSub+ .NET API: `MinimumTlsProtocolVersion` and `MaximumTlsProtocolVersion` PubSub+ Java RTO API: `MINIMUM_TLS_PROTOCOL_VERSION` and `MAXIMUM_TLS_PROTOCOL_VERSION` PubSub+ JavaScript API:`SessionProperties.tlsMinProtocol` and `SessionProperties.tlsMaxProtocol` PubSub+ Node.js API:`SessionProperties.tlsMinProtocol` and `SessionProperties.tlsMaxProtocol`	These properties specify the oldest (minimum) and most recent (maximum) TLS protocols supported. Possible values are: TLS v1.1 (`TLSv1.1`) TLS v1.2 (`TLSv1.2`) TLS v1.3 (`TLSv1.3`) The default minimum TLS protocol is TLS v1.2. The minimum and maximum TLS protocol version properties cannot be combined with the deprecated SSL excluded protocols properties.
SSL Certificate Validation	PubSub+ C API: `SOLCLIENT_SESSION_PROP_DEFAULT_SSL_VALIDATE_CERTIFICATE` PubSub+ .NET API: `SessionProperties.SSLValidateCertificate` PubSub+ Java RTO API: `SessionHandle.PROPERTIES.SSL_VALIDATE_CERTIFICATE` PubSub+ JavaScript API: N/A PubSub+ Node.js API: `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: (PubSub+ C API, PubSub+ Java RTO API, PubSub+ Node.js API, and PubSub+ .NET API) The trust store is a directory on a server that contains the trusted certificates. The default value for this property is `True`.
SSL Certificate Date Validation	PubSub+ C API: `SOLCLIENT_SESSION_PROP_DEFAULT_SSL_VALIDATE_CERTIFICATE_DATE` PubSub+ .NET API: `SessionProperties.SSLValidateCertificateDate` PubSub+ Java RTO API: `SessionHandle.PROPERTIES.SSL_VALIDATE_CERTIFICATE_DATE` PubSub+ JavaScript API: N/A PubSub+ Node.js API: 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 )	PubSub+ C API: `SOLCLIENT_SESSION_PROP_SSL_VALIDATE_CERTIFICATE_HOST` PubSub+ .NET API: `SessionProperties.SSLValidateCertificateHost` PubSub+ Java RTO API: `SessionHandle.PROPERTIES.SSL_VALIDATE_CERTIFICATE_HOST` PubSub+ JavaScript API: N/A PubSub+ Node.js API: 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	PubSub+ C API: `SOLCLIENT_SESSION_PROP_DEFAULT_SSL_CIPHER_SUITES` PubSub+ .NET API: `SessionProperties.SSLCipherSuites` PubSub+ Java RTO API: `SessionHandle.PROPERTIES.SSL_CIPHER_SUITES` PubSub+ JavaScript API: N/A PubSub+ Node.js API: `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, see PubSub+ Messaging APIs for the appropriate PubSub+ Messaging API. By default, no cipher suites are listed, which indicates that all supported ciphers should be considered. If your application negotiates a TLS 1.3 connection, you cannot select which cipher suites to negotiate with the event broker and these properties are ignored.
SSL Trusted Store Directory	PubSub+ C API: `SOLCLIENT_SESSION_PROP_SSL_TRUST_STORE_DIR` PubSub+ .NET API: `SessionProperties.SSLTrustStoreDir` PubSub+ Java RTO API: `SessionHandle.PROPERTIES.SSL_TRUST_STORE_DIR` PubSub+ JavaScript API: N/A PubSub+ Node.js API: N/A	The directory where trusted certificates are stored. The API-specific information is as follows: (PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .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, see 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)	PubSub+ C API: N/A PubSub+ .NET API: N/A PubSub+ Java RTO API: N/A PubSub+ JavaScript API: N/A PubSub+ Node.js API: `solace.SessionProperties.sslTrustStores`	The trust store files to use. The API-specific information is as follows: (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)	PubSub+ C API: N/A PubSub+ .NET API: `SessionProperties.SSLTrustStore` PubSub+ Java RTO API: N/A PubSub+ JavaScript API: N/A PubSub+ Node.js API: N/A	Indicates the trusted certificates that are available as in-memory trust store. The API-specific information is as follows: (PubSub+ .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.
SSL Trust Store Password	PubSub+ C API:N/A PubSub+ .NET API: N/A PubSub+ Java RTO API: N/A PubSub+ JavaScript API: N/A PubSub+ Node.js API: N/A	Specifies the password of the trust store.
SSL Trust Store Format	PubSub+ C API: N/A PubSub+ .NET API: N/A PubSub+ Java RTO API: N/A PubSub+ JavaScript API: N/A PubSub+ Node.js API: N/A	Indicates the format used by the trust store provided for the SSL trust store property.
SSL Connection Downgrade To	PubSub+ C API: `SOLCLIENT_SESSION_PROP_SSL_CONNECTION_DOWNGRADE_TO` PubSub+ .NET API: `SessionProperties.SSLConnectionDowngradeTo` PubSub+ Java RTO API: `SessionHandle.PROPERTIESSSL_CONNECTION_DOWNGRADE_TO` PubSub+ JavaScript API: N/A PubSub+ Node.js API: `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.

Provide feedback