Using SSL with LiveView Server

This article describes how to configure your LiveView server to use TLS (SSL) for secure connections, and how to use LiveView clients with a TLS-enabled LiveView server.

Note

The terms TLS and SSL are used interchangeably in this document, unless otherwise noted.

Introduction to TLS/SSL

Network traffic between LiveView clients and the server can run over a secure connection by enabling SSL for LiveView. This is particularly important when authentication is enabled and user names and passwords are sent over the wire.

To use SSL, configure LiveView server to listen on an SSL port, and direct LiveView clients to use SSL-enabled connections to that port. SSL client connections include:

  • Any web browser, using an https:// address. This includes access to TIBCO LiveView™ Web resources running on a LiveView Server.

  • Any Java-based LiveView client, using a connection string in lvs:// format, and for which the javax.net.ssl.trustStore and trustStorePassword system properties are specified with file system paths pointing to the Java-format truststore file and password. Such clients include:

    • The lv-client command, which reads the truststore information from the LIVEVIEW_CLIENT_JVM_ARGS environment variable.

    • TIBCO LiveView™ Desktop, which requires the truststore information to be set with a -vmargs parameter on its startup command line.

    • A custom client program that you or your organization wrote using the LiveView Java Client API.

Truststore and Keystore Files Required

The following describes the need for truststore and keystore specifications:

When SSL is enabled

The LiveView server requires:

  • A Java keystore to identify itself to LiveView clients.

  • A Java truststore (and if using authentication, a password) used by internal LiveView components that make client requests to the LiveView server.

The internal truststore holds the certificates used by the server in making internal requests to other server components.

SSL Configuration in HOCON

To enable SSL, create and edit configuration files that have following HOCON types. StreamBase Studio provides a HOCON editor invoked from the FileNewStreamBase HOCON File menu. All HOCON format configuration files must be placed in the src/main/configurations folder of your LiveView project in the Project Explorer view of StreamBase Studio. For further information about the HOCON file format and syntax, see the Configuration Guide.

Configure the portNumber and secure properties in a HOCON configuration file of type ldmclientapilistener to enable SSL and set your SSL port. The keyword secure set to true enables SSL.

name = "EnableSSL"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldmclientapilistener"

configuration = {

  ClientAPIListener = {
    portNumber = 10443
    secure = true
  }
}

Use a configuration file of HOCON type commsecurity to identify the keystore file and its password, similar to the following example:

name = "SSL"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.commsecurity"

configuration = {
  CommunicationSecurity = {
    keyStore = "/Users/sbuser/ssl/serverkeystore.jks"
    keyStorePassword = "changeit"
    }
  }
}

Use a configuration file of HOCON type ldmengine to specify the following parameters:

  • The name of the server that generates certificates (or localhost if they are generated by the local machine) using the liveview.ssl.hostname system property.

  • Use liveview.ssl.only to specify whether or not to use only SSL authentication.

  • You can optionally set authenticateUsers to false to authenticate users with SSL alone. Leaving authenticateUsers set to true means that user connections still require a name a password either from a local or LDAP security realm (as described in LiveView Authentication and Authorization), in addition to SSL authentication.

  • Add two java.net.ssl.trustStore lines to the jvmArgs section of the file.

name = "ldmengine"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldmengine"

configuration = {
  LDMEngine = {
    systemProperties = {
      "liveview.ssl.hostname"="localhost" 
      "liveview.ssl.only"="true" 
    }
    jvmArgs =
      [
        "-Xmx3g"
        "-Xms512m"
        "-XX:+UseG1GC"
        "-XX:MaxGCPauseMillis=500"
        "-XX:ConcGCThreads=1"
        "-Djavax.net.ssl.trustStore=/Users/bwright/ssl/truststore.jks"
        "-Djavax.net.ssl.trustStorePassword=changeit"      
      ]
      ldm = {
        authenticateUsers = true
      }
  }
}

Putting Certificates into a Java Keystore

The server's keystore requires:

  • Server key, which must have the CN be either the host name or the value of liveview.ssl.hostname. TIBCO recommends that the CN should be the hostname for production deployments.

The server truststore (which is the Java truststore) requires:

  • Server certificate (the LiveView certificate from the LiveView server keystore).

LiveView Clients over SSL

LiveView URI SSL Protocol and Port

To connect to a LiveView server using SSL, LiveView clients use URIs with a protocol of lvs instead of lv. When configured for SSL, a LiveView server listens on the port specified in the ldmclientapilistener file, which is traditionally 10443 for LiveView server SSL. This is also the default port of a LiveView URI when using the lvs protocol. You can override the default LiveView SSL port by adding an explicit port number to the URI, for example:

lvs://myusername:myPassword@localhost:10888

LiveView Client Trust Relationship

When connecting to LiveView through SSL, the LiveView client and server perform an SSL handshake, which includes the server sending its certificate to the client. If the client is not configured to trust the server's certificate, the handshake fails and the connection is not established.

For Java-based LiveView clients (including TIBCO LiveView Desktop, TIBCO LiveView Workspace Manager, the lv-client command, and any custom Java client application your organization writes with the LiveView Java Client API), the trust relationship can be configured by setting the javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword properties for the JVM that runs the client.

The following is an example of using an environment variable to set the required system property settings for LiveView clients such as lv-client that honor environment variables. The actual setting of this variable is dependent on your platform.

LIVEVIEW_CLIENT_JVM_ARGS="-Djavax.net.ssl.trustStore=/Users/sbuser/sitetruststore.jks \
  -Djavax.net.ssl.trustStorePassword=secret1ve" 

Configuring the trust relationship for non-Java LiveView clients is beyond the scope of this document.