Reference for StreamBase CommSecurity Configuration

Overview

This article provides a reference for writing a StreamBase CommSecurity HOCON configuration file.

The secure communication configuration sets keystores and trust stores for secure client API and LDAP transport communication. It is separate from the base engine configuration and can therefore be managed separately without having to recreate an application archive and redeploy the application.

Required Header Lines

Each configuration file must contain the following header lines, typically found at the beginning of each file:

name

Specifies an arbitrary, case-sensitive string to name this configuration, which must be unique among other files with the same type, if any. Configuration files can refer to each other by this name. Select a name that reminds you of this configuration's type and purpose. For example:

name = "mycommunicationsettings"
version

Specifies an arbitrary version number that you can use to keep track of file versions for this configuration type in your development project. The maintenance of version numbers is under user control; StreamBase does not compare versions when loading configuration files during the fragment launch process. The version number is a string value, and can contain any combination of characters and numbers. For example:

version = "1.0.0"
type

This essential setting specifies the unique HOCON configuration type described on this page.

type = "com.tibco.ep.streambase.configuration.commsecurity"

The header lines taken together constitute a unique signature for each HOCON file in a project's configurations folder. Each project's configurations folder can contain only one file with the same signature.

In addition, the configuration top-level element is the same for all HOCON file types.

configuration

On a line below the header element lines, enter the word configuration followed by an open brace. The configuration element is a sibling of the name, version, and type elements, and serves as a wrapper around this type's elements described below. The file must end with the matching close brace.

configuration = {
...
...
}

HOCON Elements Explained

Below shows the configuration's HOCON elements, its name-values, usage, and syntax example, where applicable.

CommunicationSecurity

A class describing communication transport security as used by StreamBase and Live Datamart. Only one instance per node is permitted.

keyStore

String. File path to a keystore that contains the server's certificate as well as optional trust store information, depending on keystore format. It must be a file, since the implementation uses the JSSE system property javax.net.ssl.keystore to make the keystore available to SSL, and that must be a file. If the keystore contains multiple private key entries ("aliases" in JKS parlance), the first is used; the existing StreamBase implementation does not allow an alias to be specified. The path is required to be absolute, therefore the file must exist on the target node's file system.

This name-value pair is required.

For example:

keyStore = "/absolute/path/myKeyStore.jks"
keyStorePassword

String. Keystore password, used to access the keystore contents. You can provide an enciphered string for the value; generate the enciphered string with the sbcipher command and prefix #! to the generated string. This name-value pair is required.

For example:

keyStorePassword = "secret"
keyPassword

String. The password to access the key within the keystore. You can provide an enciphered string for the value; generate the enciphered string with the sbcipher command and prefix #! to the generated string. This name-value pair is optional; if absent, the keystore password is used to access the name-value pair.

For example:

keyPassword = "anothersecret"
clientAuthentication

If present, only client connections that have a certificate signed by a trusted certificate authority will be allowed. This is sometimes called client-side authentication or two-way TLS/SSL. If absent, SSL connections will be accepted from any clients. This is sometimes called one-way SSL. This name-value pair is optional and has no default value.

trustStore

Trust store containing CAs by which client certificates must be signed to be trusted. Same comments as for the keystore property above: must be a file; generator responsible for setting system property to an absolute file name. The path is required to be absolute, therefore the file must exist on the target node's file system. This name-value pair is required.

For example:

trustStore = "/absolute/path/myTrustStore.jks"
trustStorePassword

The password to access the trust store. You can provide an enciphered string for the value; generate the enciphered string with the sbcipher command and prefix #! to the generated string.

For example:

trustStorePassword = "athirdsecret"
cipherSuites

An array of cipher suites that can be used for SSL encryption. If this element is not listed, StreamBase uses all the cipher suites that are installed with the JVM. When this element is present, StreamBase is limited to the suites you list.

For example:

cipherSuites = [
"SSL_RSA_WITH_RC4_128_MD5"
"SSL_RSA_WITH_RC4_128_SHA"
]

HOCON Configuration File Sample

The following is an example of the com.tibco.ep.streambase.configuration.commsecurity type.

name = "mycommunicationsettings"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.commsecurity"
configuration = {
  CommunicationSecurity = {

    keyStore = "/absolute/path/myKeyStore.jks"
    keyStorePassword = "secret"
    keyPassword = "anothersecret"
    clientAuthentication = {
      trustStore = "/absolute/path/myTrustStore.jks"
      trustStorePassword = "athirdsecret"
      cipherSuites = [
        "SSL_RSA_WITH_RC4_128_MD5"
        "SSL_RSA_WITH_RC4_128_SHA"
      ]
    }
  }
}