Using SSL with LiveView Server

Contents

Introduction to TLS/SSL
Server Configuration for SSL
Truststore and Keystore Files Required
Configuration for Truststore and Keystore Files
SSL with Client Certificate Authentication
Putting Certificates into a Java Keystore
Configuring LiveView Clients to Use SSL
SSL with Client Certificate Authentication
Fine-tuning TLS Client Certificate Configuration

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.

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.

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 lv-server command and its --liveview-ssl-port option. For example: 

    lv-server --liveview-ssl-port 10443 run path/to/lv/project

  • In your LiveView project's liveview.properties file, add a line like the following: 

    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, set the liveview.ssl.port property like the following example: 

    <java-vm>
    <sysproperty name="liveview.ssl.port" value="10443"/>
</java-vm>

Truststore and Keystore Files Required

There are two cases that determine the need for various 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.

When SSL with client certificates is enabled

The LiveView server requires:

  • A Java truststore and keystore to identify itself to LiveView clients.

  • A Java truststore and keystore used by internal LiveView components that make client requests to the LiveView server.

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

Configuration for Truststore and Keystore Files

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_.*"/>

SSL with Client Certificate Authentication

If you want to enable SSL with client certificate authentication, set the following properties in your sbd.sbconf file: 

<sysproperty name="liveview.require.client.authentication" value="true" />
<sysproperty name="javax.net.ssl.keyStore" value="internalkeystore.jks"/>
<sysproperty name="javax.net.ssl.keyStorePassword" value="internalkeystorepassword"/>

Note

As of release 2.2.3, the system property:

<sysproperty name="liveview.require.client.authentication" value="true" />

Replaces

<sysproperty name="liveview.security.auth.requireX509" value="true" />

Which is still supported but is now deprecated.

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

liveview.security.auth.filter=clientCert

Note

As of release 2.2.3, the following line:

liveview.security.auth.filter=clientCert

Replaces

liveview.security.auth.filter=x509

Which is still supported but is now deprecated.

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 scheme (whether for LDAP or basic authorization configured in the liveview.properties file).

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 hostname 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 that the CN should be the hostname for production 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 X.509-format certificates). Any user certificate signed by the CA passes authentication when X.509 authentication is enabled.

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:

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

  • LiveView internal user certificate

Configuring LiveView Clients to Use SSL

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

Browsers Specify 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. If your LiveView server specifies a non-default port, you can override the default LiveView SSL port in the client access URI by adding an explicit port number. For example: 

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

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.

.NET Client TLS Configuration

If you are connecting to a TLS-enabled LiveView server with .NET 4.5 or lower, be advised the default TLS options are incompatible with LiveView. LiveView only supports only TLS 1.1 and later and does not support the insecure TLS 1.0 or earlier versions.

The default for .NET 4.5 and earlier is only TLS 1.0. To enable TLS 1.1 or 1.2 for your .NET client, you must do one one of the following:

  • configure the system registry

  • set ServicePointManager.SecurityProtocol (in your code)

  • compile and run with .NET 4.6 (or later)

SSL with Client Certificate Authentication

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"

Fine-tuning TLS Client Certificate Configuration

When fine-tuning TLS client certificates, TIBCO recommends setting up the lookup object identifiers (OIDs), which are used to pull the username for authorization out of the certificates. An OID is a numeric value that identifies the application or service for which a certificate is used.

If possible, use only one OID as shown in the section below. Setting these properties incorrectly may lead to security vulnerabilities.

Configuring Certificate Username Lookup

This property 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 property is empty, it then tries to use the commonName attribute (OID = 2.5.4.3). Finally, if neither property 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. This is a list of comma-separated values, or full. Note that using these properties is lightly discouraged in production environments because of potential security implications (for example, if your certificate is visible and its numbers match the numbers that appear in the OID configuration). If possible, use only one OID in this property to minimize exposure.

Be careful, as fallbacks can expose potential security vulnerabilities; 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

Using Server Certificates as Internal User

If you want to use your server certificate as your internal user certificate, configure these properties in the liveview.properties file to rewrite your domain name into your internal user. This configuration is not intended for the LVInternal user but possibly for testing TLS web client authentication via extended key usage. 

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). Also, the domain name set in the property above should be set for the internal user you define in the property below.

Configure the following for the internal user:

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.