Using SSL with LiveView Server

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:

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 only on its SSL port, set the liveview.ssl.only property to true, either in your LiveView project's liveview.properties or in your LiveView project's StreamBase configuration file.

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

There are two cases that determine the need for various truststore and keystore specifications:

In both cases, the internal truststore holds the certificates used by the server in making internal requests to other server components.

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 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:

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

If you want to enable SSL with client certificate authentication, 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"/>

Also add the following line to your liveview.properties file:

liveview.security.auth.filter=x509

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

Note that enabling SSL only applies to authentication, not authorization. You will also need an authorization schema (whether for LDAP or basic authorization configured in the liveview.properties file).

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

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

If X.509 support is enabled, X.509 authentication is required for all connections, including from the LiveView internal user. Therefore, 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 X.509. For X.509 authentication only, the server internal keystore (javax.net.ssl.keyStore property) requires:

If the LiveView server is configured to accept client connections using SSL authentication, then every LiveView client must have a matching setting.

lvs://myusername:myPassword@localhost:10888  // Example of non-standard port number

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

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

TIBCO LiveView Web™ is ready to work with client certificate authentication, and does not require any additional configuration.

Clients such as the lv-client command or custom-written clients can present their certificate to the LiveView server using the following URI style (shown here with line breaks for legibility):

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

As an alternative, clients can make the same settings as system properties, using the liveview.ssl.keyStore and liveview.ssl.keyStorePassword keywords.

Clients can also use the LIVEVIEW_CLIENT_JVM_ARGS environment variable to specify the keystore from which the client certificate is retrieved. For example (shown here with line breaks for legibility):

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

If you do not have the truststore set system-wide, then you must specify both truststore and client keystore. For example:

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

When using SSL with LDAP, TIBCO recommends setting up the lookup OIDs, which are used to pull the username for authorization out of the certificates. Setting this incorrectly may lead to security breaches. This is a list of comma-separated values, or full. Be careful, as fallbacks cannot expose security flaws; make sure your certificate authority or keystore does not approve malicious certificates that contain multiple valid usernames in each fallback:

liveview.security.auth.X509.usernamelookupOIDs=1.2.840.113549.1.9.1,2.5.4.3,full

This line attempts to pull the OID representing emailAddress (OID = 1.2.840.113549.1.9.1) first, and use that as the username of the person logging in for the authorization layer. If this attribute is empty, it then tries to use the commonName attribute (OID = 2.5.4.3). Finally, if neither attribute exists, the full subject of the certificate is used. For example: CN=lvintern,CN=Users,DC=example,DC=tibco,DC=com. If you need to use the entire certificate subject, use the argument full to accomplish this.

If you have a custom or non-standard OID in each certificate, you can specify the number.

If you want to use your server certificate as your internal user certificate (for example for testing purposes), configure the following two properties in the liveview.properties files. Note that these properties are not intended for production environments:

liveview.security.auth.X509.internal.principal=localhost

The above property is the CN or email that would normally be pulled out of the server certificate (normally the domain name).

Then configure the following for the username:

liveview.security.auth.X509.internal.user=lvintern

This property applies to the username (which usually is always going to be lvintern) you want to substitute for the principal above.