Using SSL with LiveView Server

Introduction to SSL and TLS

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.

Note

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

To use SSL, configure LiveView server to listen on an SSL port, and direct LiveView clients to use SSL-enabled connections to that port. When SSL is enabled, the LiveView server, by default, listens on both a non-SSL port and an SSL port. To configure the server to listen on an SSL port only, set the liveview.ssl.only property to true, either in your LiveView project's liveview.properties or StreamBase configuration (sbd.sbconf) file.

Server Configuration for SSL

SSL is enabled in the LiveView server by setting the liveview.ssl.port property in one of three ways:

Start the LiveView server with the --liveview-ssl-port option of the lv-server command:
```
lv-server --liveview-ssl-port 10443 run <path-to-lv-project>
```
In your LiveView project's liveview.properties file, uncomment the line that sets the LiveView SSL port:
```
liveview.ssl.port=10443
```
A template liveview.properties file is provided with the LiveView Authentication and Authorization sample.
In the <java-vm> element of your LiveView project's StreamBase configuration file, sbd.sbconf, set the liveview.ssl.port property:
```
<java-vm>
    <sysproperty name="liveview.ssl.port" value="10443"/>
</java-vm>
```

When SSL is enabled, the LiveView server requires a Java keystore and password to identify itself to LiveView clients, and a Java truststore and password for internal LiveView components that make client requests to the LiveView server. The LiveView Authentication and Authorization sample provides a prepopulated keystore file that is used for both roles, and is configured within the sample's StreamBase configuration file, sbd.sbconf, as follows:

<sysproperty name="liveview.keystore" value="mykeystore"/>
<sysproperty name="liveview.keystore.password" value="mypassword"/>
<sysproperty name="javax.net.ssl.trustStore" value="mykeystore"/>
<sysproperty name="javax.net.ssl.trustStorePassword" value="mypassword"/>

Your site may have specific requirements for the protocols and cipher suites used in establishing secure connections. Two system properties are available for this: one to exclude specific protocols and another to exclude cipher suites. Each property contains a comma-delimited list of protocols or cipher suites to exclude, and the cipher suite-related property can contain regular expressions. Following are example uses of the properties in the StreamBase configuration file, sbd.sbconf:

<sysproperty name="liveview.excluded.protocols" 
  value="SSLv2,SSLv3,TLSv1,TLSv1.1"/>
<sysproperty name="liveview.excluded.cipher.suites" 
  value=".*_DHE_.*"/>

If you want to enable two-way client-side authentication over SSL, add the following line to your liveview.properties file. Note that enabling SSL only applies to authentication, not authorization. You will also need an authorization schema (whether for LDAP or configured in the liveview.properties file).

liveview.security.auth.filter=x509

and set the following properties in your sbd.sbconf file:

<sysproperty name="liveview.security.auth.requireX509" value="true" />
<sysproperty name="javax.net.ssl.keyStore" value="internalkeystore.jks"/>
<sysproperty name="javax.net.ssl.keyStorePassword" value="internalkeystorepassword"/>

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

Putting Certificates into a Java Keystore

The server keystore (specified in the liveview.keystore property) requires:

Server key, which must have the CN be either the host name or the value of liveview.ssl.hostname. For testing purposes it may be useful to set the liveview.ssl.hostname to localhost and then generate self-signed certificates for localhost. TIBCO recommends the CN should be the hostname for deployments.

The server truststore (specified in the javax.net.ssl.trustStore property), which is the Java truststore, requires:

Server certificate (the LiveView certificate from the LiveView server keystore)
User CA (only for x509). Any user certificate signed by the CA passes authentication when x509 authentication is enabled.

As x509 authentication is required for all connections including the LiveView internal user, you must provide keys for the internal user as well. These replace the properties as specified in LiveView Authentication and Authorization and do not need to be set when using x509. For x509 authentication only, the server internal keystore (javax.net.ssl.keyStore property) requires:

LiveView internal user key (must be signed by user's CA)
LiveView internal user certificate

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 by default on port 10443. 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.

When using the LiveView Authentication and Authorization sample, the server's certificate is located in the mykeystore file provided with the sample.

The following is an example of using an environment variable to specify the system property settings for all LiveView clients. The actual setting of these variable is dependent on your platform.

LIVEVIEW_CLIENT_JVM_ARGS="-Djavax.net.ssl.trustStore=sitetruststore.jks -Djavax.net.ssl.
  trustStorePassword=secret1ve"

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

Client-Side Certificate (Two-Way) Authentication

If the LiveView sever is configured for client-side certificate authentication, the client must present a certificate to the server during the TLS handshake.

LiveView Web does not require any additional configuration. Other clients can present their certificate to the LiveView server using the following URI style (first line breaks to the second here for legibility):

lvs://localhost:10443?x509-keystore=../keystore/with/only/client/key.jks&x509-
  keystore-password=secret1ve

OR use the system properties liveview.ssl.keyStore and liveview.ssl.keyStorePassword.

Alternatively, you can use an environment variable to specify the keystore from which the client certificate is retrieved. For example:

LIVEVIEW_CLIENT_JVM_ARGS="-Djavax.net.ssl.keyStore=mykeystore.jks -Djavax.net.ssl.
  keyStorePassword=secret1ve"

If you do not have the truststore set system-wide, then you must still specify the truststore. For example:

LIVEVIEW_CLIENT_JVM_ARGS="-Djavax.net.ssl.trustStore=mytruststore.jks -Djavax.net.ssl.
  trustStorePassword=secret1ve -Djavax.net.ssl.keyStore=mykeystore.jks -Djavax.net.ssl.
  keyStorePassword=secret1ve"