Enciphering Passwords and Parameter Values

The following shows partial example configuration entry for access to a Microsoft SQL Server database. (The full example is on JDBC Data Source Overview.)

...
configuration = {
    "JDBCDataSource" = {
      driverClassName = "com.microsoft.sqlserver.jdbc.SQLServerDriver"
      serverURL = "jdbc:sqlserver://mssql2012.lab.streambase.com\\DBname"
      userName = "sqluser"
      password = "Secr3t1ve"
      operationTimeoutMilliseconds = 200000
...

To preserve the privacy of this information, you can encipher the login name and password, using sbcipher commands at a StreamBase-configured shell prompt for macOS and Linux, or the StreamBase Command Prompt on Windows.

For example, first encipher the username:

sbcipher -c sqluser

This command returns:

jbWZzLOJupC1qI7T9d7VRLbXH5RwMJauuQinFLq5jKbhsZB0qUzueF5YS5
eQLdfiN2uc3SEeXlyS3A9umPwGxA

(The enciphered strings returned are shown in these examples with line breaks inserted for publication clarity. The string returned is actually a single unbroken string.)

Now, encipher the password:

sbcipher -c Secr3t1ve

This command returns:

aSCxFiNjVZ4CbcssDUU9QS345DXyn393GX+lp0JH7EN12T02fgz672/91
ItbTYMK4A0t12CJNPfvK3EEVt/r+Q==

Now, edit the configuration file to add the enciphered attribute, and to specify the enciphered strings returned to standard output by the sbcipher command. For example:

...
configuration = {
    "JDBCDataSource" = {
      driverClassName = "com.microsoft.sqlserver.jdbc.SQLServerDriver"
      serverURL = "jdbc:sqlserver://mssql2012.lab.streambase.com\\DBname"
      userName = "#!jbWZzLOJupC1qI7T9d7VRLbXH5RwMJauuQinFLq5jKbhsZB0qUzueF5YS5
                  eQLdfiN2uc3SEeXlyS3A9umPwGxA"
      password = "#!aSCxFiNjVZ4CbcssDUU9QS345DXyn393GX+lp0JH7EN12T02fgz672/91
                  ItbTYMK4A0t12CJNPfvK3EEVt/r+Q=="
      operationTimeoutMilliseconds = 200000
...

The following shows one line from a configuration file for a MySQL database. In this case, the database login name and password are embedded in the JDBC connection string, not in separate lines:

serverURL = "jdbc:mysql://mysql.example.com:3306/qa?user=nonnymouse&password=secret"

For databases like MySQL that embed the user name and password in the connection string, you must encipher the entire URI value with steps like the following:

To use your generated server key in place of the embedded server key to decipher all enciphered values, specify the path to your server key file with the streambase.security.key-file system property. Use the systemProperties object in a configuration file of type sbengine, in the root object StreamBaseEngin:

...
  StreamBaseEngine = {
    systemProperties = {
      "streambase.security.key-file" = "/path/to/myCompanyKey.server"
...

When you specify one server key file, you override and disable the default embedded server key. You can preserve the embedded server key while also using a generated server key as described below.

You can specify a comma-separated list of server keys. In this case, when the StreamBase server encounters an enciphered value in the configuration file, it tries to decipher using each server key in the order listed. For example:

...
  StreamBaseEngine = {
    systemProperties = {
      "streambase.security.key-file" = "myCompanyKey.server,cipherKey.server"
...

This feature allows you to encipher different portions of the configuration file for different purposes. For example, your site's database administrators may prefer to keep private a particular database's login name and password. You can provide them with the sbcipher command so they can encipher those values and return to you only the enciphered strings, plus a pair of client and server key files.

When you specify one or more server key files with the streambase.security.key-file system property, you disable the embedded server key described in Enciphering with the Embedded Key Pair. However, there is a way to continue using the embedded keys for some purposes, but use a generated server key for other purposes.

Two files containing the embedded server keys are delivered with your StreamBase installation. Locate these files in the /etc folder of your StreamBase installation with the following names:

You can specify one or both of these server key files in your list of server keys in the streambase.security.key-file system property. For example:

...
  StreamBaseEngine = {
    systemProperties = {
      "streambase.security.key-file" = "/path/to/myCompanyKey.server,
       ${STREAMBASE_HOME}/etc/streambase-embeddedkey-512.server"
...

Assuming the server's environment has the STREAMBASE_HOME variable set, this directive says to decipher enciphered values using the myCompanyKey.server key first, then try using the default embedded 512-bit key.

StreamBase Studio needs to decipher enciphered values under two circumstances:

If the configuration file has values enciphered with the default embedded keys, then Studio can successfully typecheck operators, and can successfully launch and run applications normally.

However, if the configuration file has values enciphered with custom generated keys, Studio must know where to locate the server key or keys used when enciphering the values. Specify the location of custom generated server keys to Studio using the streambase.security.key-file system property specified as part of the STREAMBASE_STUDIO_VMARGS environment variable. You must set the value in this environment variable before starting Studio.

Set this variable as described in STREAMBASE_STUDIO_VMARGS. When adding the streambase.security.key-file system property, remember to re-specify the default -Xms and -Xmx arguments, as shown in the following example:

STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx768M \
    -Dstreambase.security.key-file=/path/to/myCompanyKey.server