Using TLS/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 TLS for LiveView. This is particularly important when authentication is enabled and user names and passwords are sent over the wire.

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

  • Any web browser when 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.

Consider the following when configuring TLS for LiveView:

  • If you are configuring TLS of any kind (TLS on LiveView server or TLS with client certification on a LiveView server), the server profile must have a keystore and a truststore configured as shown in the next section, and the client profile truststore must be the same as the server profile.

  • If you are configuring TLS-enabled LDAP, the client profile truststore must contain a root certificate for the LDAP server.

  • If you are configuring TLS client certificate authentication for LiveView, the client profile keystore must be the internal user's private key. Also, the server profile truststore must contain the certificate authority for the allowed users. Additionally, you must set the requireClientAuthentication = true property in BOTH the client and server profiles.

  • If you specify the server profile, you must also specify the client profile.

Note

TLS configuration is a complex subject. This page presumes knowledge of Java Cryptography Architecture in general, and knowledge of which Java Cryptography Architecture provider you intend use, or that your organization mandates that you use. The simplest starting point may be to use the keytool command, provided as part of your Java installation, to create and populate your keystore and truststore. However, there are newer and stronger cryptography providers available.

Truststore and Keystore Files Required

The following describes the need for truststore and keystore specifications:

When TLS 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.

TLS Configuration in HOCON

To enable TLS, create and edit configuration files of the types shown below. StreamBase Studio provides a HOCON editor invoked from File>New>StreamBase HOCON Configuration File. These configuration files must be placed in the src/main/configurations folder of your LiveView project.

  • ldmclientapilistener — specifies name of this authentication realm, the port for the TLS-enabled server, and specifies which

  • SecureCommunicationClientProfile — specifies the TLS configuration for internal server-to-server communication.

  • SecureCommunicationServerProfile — specifies the TLS configuration that external clients use to communicate with the LiveView server.

  • LDMEngine — specifies a system property that identifies your TLS-enabled LiveView server's hostname. This may not be required if hostname resolution occurs normally for your server.

Client API Listener Configuration

Use a HOCON configuration file of type ldmclientapilistener to define and name this authentication realm and to set the port one which the TLS-enabled server listens for connections. The traditional TLS port for LiveView is 10443. This file also identifies the client profile to use.

For example:

name = "enableTLS"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldmclientapilistener"
configuration = {
  ClientAPIListener = {
    portNumber = 10443    
    authenticationRealmName = "authRealm"
    secureCommunicationProfileName = "TLSclient"
  }
}

Client Security Configuration

Use a configuration file of HOCON type security with root object SecureCommunicationClientProfile to identify the keystore file and its password. Each profile has a unique name across all server and client profile types; the name serves as a reference target from other configurations wishing to enable secure communication.

The following is a sample that configures a secure communication profile for a client endpoint. A secure communication profile configuration object contains settings used to secure client-side transport connections (for example, to external services such as LDAP). Profiles are named and then referenced as needed by other configurations needing secure communication.

For example:

name = "TLSclientsettings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  SecureCommunicationClientProfile = {
    name = "TLSclient"
    keyStore = "/absolute/path/to/myKeyStore.jks"
    keyStorePassword = "secret"
    keyPassword = "anothersecret"
    keyStoreType = "JKS"
    trustStore = "/absolute/path/to/myTrustStore.jks"
    trustStorePassword = "athirdsecret"
    trustStoreType = "JKS"
    requireClientAuthentication = false
  }
}

Server Security Configuration

The server profile is for the API listener in your LiveView server. For TLS with client certificate authentication, the profile contains a trust store used to validate incoming server certificates.

If you enable TLS on a LiveView server, you need both the SecureCommunicationClientProfile and the SecureCommunicationServerProfile configured. This is due to the server and client certificates having different attributes, and CAs do not issue a single certificate appropriate for both client and server use.

For example:

name = "TLSserversettings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  SecureCommunicationServerProfile = {
    name = "TLSserver"
    keyStore = "/absolute/path/myKeyStore.jks"
    keyStorePassword = "secret"
    keyPassword = "anothersecret"
    keyStoreType = "JKS"
    trustStore = "/absolute/path/myTrustStore.jks"
    trustStorePassword = "athirdsecret"
    trustStoreType = "JKS"
    requireClientAuthentication = false
    userNameObjectIdentifierSearchPath = [ "userID", "CN", "1.2.3.4", "DN" ]
  }
}

The default SecureCommunicationServerProfile contains a excludedCipherSuitePatterns property that excludes the cipher suites.

excludedCipherSuitePatterns = [ "^SSL_.*$","^.*DH_.*$","^.*KRB5.*$","^.*NULL.*$","^.
  *anon.*$","^.*DES.*$","^.*MD5$","^.*DSS.*$","^TLS_RSA(?:(?!_WITH_AES_128_CBC_SHA).)
  *$"]

Engine Configuration

Use a configuration file of HOCON type ldmengine to specify the name of the server as expected in the DN field of the certificate, using the liveview.ssl.hostname system property.

The certificate used by your server is selected automatically based on the server's hostname. Use this system property if you get errors trying to find the certificate for your hostname, such as when the hostname that the LiveView server tried to find is incorrect.

For example:

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

configuration = {
  LDMEngine = {
    systemProperties = {
      "liveview.ssl.hostname" = "lvserver201.example.com" 
    }
    ...
  }
}

Putting Certificates into a Java Keystore

The server keystore (which is specified in the SecureCommunicationServerProfile 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 SecureCommunicationServerProfile trustStore property) 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.

The client truststore (specified in the SecureCommunicationClientProfile trustStore property) requires:

  • Server certificate CA (the LiveView certificate from the LiveView server keystore or the LiveView server certificate's CA).

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. For X.509 authentication only, the client profile keystore (SecureCommunicationClientProfile keyStore property) requires:

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

  • LiveView internal user certificate

TLS with Client Certificate Authentication

To enable TLS with client certificate authentication:

  • Configure the keyStore property in the commsecurity configuration file.

  • Set the property requireClientAuthentication = true in BOTH the commsecurity and serversecurity configuration files.

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

Note that enabling TLS only applies to authentication, not authorization. You also need an authorization scheme, whether for LDAP, basic, or another authorization scheme. These are configured in HOCON configuration files of type com.tibco.ep.dtm.configuration.security, where the root object determines the authorization scheme.

LiveView Clients over TLS

LiveView URI TLS Protocol and Port

To connect to a LiveView server using TLS, LiveView clients use URIs with a protocol of lvs instead of lv. When configured for TLS, a LiveView server listens on the port specified in the ldmclientapilistener file, which is traditionally 10443 for LiveView server TLS. This is also the default port of a LiveView URI when using the lvs protocol. You can override the default LiveView TLS 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 TLS, the LiveView client and server perform an TLS 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 trustStore and trustStorePassword properties in the SecureCommunicationClientProfile root object for the security configuration type 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.

.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)

Fine-tuning TLS Client Certificate Configuration

When fine-tuning TLS client certificate configurations, TIBCO recommends setting up the lookup object identifiers (OIDs) — or their friendlier name-value pairs — in a HOCON configuration file of type SecureCommunicationServerProfile. OIDs 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

The userNameObjectIdentifierSearchPath 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).

For example: CN=lvintern,CN=Users,DC=example,DC=tibco,DC=com.

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

  userNameObjectIdentifierSearchPath = [
    "emailAddress",
    "userID",
    "CN",
    "DN"
  ]

Using Server Certificates as Internal User

If you want to use your server certificate as your internal user certificate, configure these properties in the configuration file of type ldmengine 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. For example:

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

configuration = {
  LDMEngine = {
    systemProperties = {
      "liveview.ssl.hostname" = "localhost" 
      "liveview.security.auth.X509.internal.principal"="localhost"
      "liveview.security.auth.X509.internal.user"="lvintern"
     }
      jvmArgs = [
      "-Xmx1024m"
      "-Xms512m"
      "-XX:MaxPermSize=768m"
    ]
  }
}