Enciphering Passwords and Parameter Values

The following shows an example <data-source> entry for an Oracle database:

<data-sources>
  <data-source name="Oracle_10g" type="jdbc">
    <driver value="oracle.jdbc.driver.OracleDriver"/>
    <uri value="jdbc:oracle:thin:@orasrv.example.com:1521:sb_test"/>
    <param name="user" value="orauser"/>
    <param name="password" value="secret"/>
    ...
    </data-source>
</data-sources>

This leaves the Oracle login name and password visible in clear text in the configuration file, readable by anyone with access to the file. To preserve the privacy of this information, you can encipher the Oracle login name and password, using sbcipher commands at a UNIX command prompt or the StreamBase Command Prompt on Windows. For example, first encipher the username:

sbcipher -c "orauser"

This command returns:

b0gyqMSZ5D4lEsy0BdTmxpf+AAWDpbnkUWj0G6HaLuIuG6gKwX90ybHL0Z7yVo+T8D66sKmPso0NcDQwYX1idA==

Now, encipher the password:

sbcipher -c "secret"

This command returns:

M5DSWylszg5aA9AK29MOiaDLq7SMqmTor+nW3qURTrT9E9eqJfTPyyUudCK34nhXHE53PXK6pregp4MW8qrueg==

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:

<data-sources>
  <data-source name="Oracle_10g" type="jdbc">
    <driver value="oracle.jdbc.driver.OracleDriver"/>
    <uri value="jdbc:oracle:thin:@orasrv.example.com:1521:sb_test"/>
    <param name="user" enciphered="true" 
      value="b0gyqMSZ5D4lEsy0BdTmxpf+AAWDpbnkUWj0G6HaLuIuG6gKwX90ybHL0Z7yVo+T8D66sKmPso0NcDQwYX1idA=="/>
    <param name="password" enciphered="true"
      value="M5DSWylszg5aA9AK29MOiaDLq7SMqmTor+nW3qURTrT9E9eqJfTPyyUudCK34nhXHE53PXK6pregp4MW8qrueg=="/>
    ...
    </data-source>
</data-sources>

The following shows an example <data-source> entry for a MySQL database. In this case, the database login name and password are embedded in the JDBC connection string, not in separate <param> lines:

<data-sources>
  <data-source name="MYSQL" type="jdbc">
    <driver value="com.mysql.jdbc.Driver"/>
    <uri value="jdbc:mysql://mysql.example.com:3306/qa?user=nonnymouse&amp;password=secret"/>
    <param name="jdbc-reconnect-attempts" value="5"/>
    ...
  </data-source>
</data-sources>

For databases like MySQL and Microsoft SQL Server 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 <sysproperty> child element of the <jvm-args> element in the server configuration file, as shown in the following example:

<jvm-args>
  ...
  <sysproperty name="streambase.security.key-file"
      value="/path/to/myCompanyKey.server" />
  ...
</jvm-args>

When you specify one server key file as in the example above, 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 StreamBase Server encounters an enciphered value in the configuration file, it tries to decipher using each server key in the order listed. For example:

<jvm-args>
  ...
  <sysproperty name="streambase.security.key-file"
      value="myCompanyKey.server,myKey.server,cipherKey.server" />
  ...
</jvm-args>

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 streambase-install-dir/etc 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:

<jvm-args>
  ...
  <sysproperty name="streambase.security.key-file"
      value="/path/to/myCompanyKey.server,${STREAMBASE_HOME}/etc/streambase-embeddedkey-512.server" />
  ...
</jvm-args>

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

You may want to re-specify the default GC settings as described in Garbage Collection Policy Settings.