Encrypting Sensitive Configuration Data

< Previous		Next >

Overview

StreamBase HOCON configuration files might store sensitive data, which must be encrypted to prevent unauthorized disclosure.

StreamBase relies on a master secret cryptographic key to encrypt sensitive data, created with the epadmin create secret command. This command generates a random cryptographic shared secret and places it in a user-specified keystore file. The keystore must be encrypted with a user-specified password.

The overall steps to use the master secret mechanism are as follows:

Create a master secret key file locally.
Use that key to encrypt strings in configuration files.
Load the same key into the node that will contain your EventFlow or LiveView fragment.
When your fragment is running, the StreamBase Runtime automatically decrypts any encrypted strings.

The same steps in more detail follow:

Create a master secret key file in any local machine location, using any arbitrary file name and optional extension. The extension .ks (for keystore) is a traditional but not mandatory extension. A node does not need to exist yet for this step. Examples:
```
epadmin create secret --keystore=lockbox.ks
epadmin create secret --keystore=lockbox --keystorepassword=secretive
epadmin create secret --keystore=$HOME/Documents/donoterase/lockbox
epadmin create secret --keystore=%HOMEPATH%\Documents\donoterase\lockbox
```
All keystore files must have a password. If you do not specify one on the create secret command line with the --keystorepassword option, epadmin prompts for a password, then prompts again to confirm the entered password. The keystore file is not created unless you enter exactly matching passwords.

Note

In all subsequent epadmin commands that specify --keystore, if you do not also specify the --keystorepassword option, epadmin prompts for the keystore's password. The command fails if the password does not match the one specified with epadmin create secret.
Edit configuration files for your fragment as usual. When a configuration calls for writing an encryptable property in a configuration file, first encrypt that value on the command line with the same master secret key. A node does not need to exist yet for this step.

For example, to encrypt the password s3KriTly for an adapter connection specified in a configuration file:
```
epadmin encrypt secret --keystore=/path/to/lockbox 
    --keystorepassword=secretive --data=s3KriTly
```
If you do not specify the --data parameter, epadmin prompts for the string to encrypt, then prompts to confirm the string.

This command returns a long string to standard output. Copy that long string into your configuration file to replace the encryptable value with its encrypted string. Be sure to include the initial #!! encryption indicator characters in the encrypted string you paste.
Load the master secret key into the node that will contain your EventFlow or LiveView fragment. Until the key is loaded into the node, if the configuration files for any of your node's fragments contain encrypted values, the StreamBase Runtime rejects any attempt to activate such configurations, or to install the node (which activates its configurations).

You can load the secret key at node installation time or later, into a stopped or running node:
Load key at node install time using epadmin
```
epadmin install node --nodename=A.sbuser 
    --application=deployment-application.zip
    --nodedirectory=$HOME/nodedirs --keystore=/full/path/to/lockbox
    --keystorepassword=secretive
```
Load key at node install time in StreamBase Studio

Open the Run Configuration for your EventFlow or LiveView fragment. In the Node tab, in the Node Installation Properties grid, add keystore and keystorepassword entries and their values, using the full absolute path for the keystore value. Click Apply to save the values, then optionally click Run to run the fragment now.

After these values are set, running this fragment in Studio loads the same secret file without needing to reopen the Run Configuration.

Note

If the Run>Run Configurations dialog does not have an entry for your fragment in the EventFlow Fragment or LiveView Fragment sections, it is simpler to run the fragment one time so that Studio creates the baseline run configuration for you — even if running the fragment this way fails. Then come back into the dialog to add the Node Installation Properties for your fragment.

Load key into a running node

You can load a master secret key into a stopped or running node with the epadmin load secret command. This case is discussed in the next section.
When your fragment is running, any encrypted configuration values are automatically decrypted by the StreamBase Runtime using the master secret key that you installed in or uploaded to the node.

With this system, notice that:

During encryption, the master secret key's password is only used locally on the developer's machine, and does not travel over the network.
During decryption, the encrypted master secret key is only used internally by the StreamBase Runtime, and does not travel over the network.
The only values ever shared between nodes over the network, if any, are encrypted.

Using the load secret Command

You can load a master secret key one time into a stopped or running node that has no secret already installed. This case is designed to allow long-running, stable node clusters to begin using encrypted values after initial installation without encryption, or to allow development of a node to proceed without encryption considerations in the project's early stages. The sequence of events will fit the following pattern.

You install and start the node with a set of HOCON configuration files that have no encrypted values:
```
epadmin install node nodename=A.sbuser ...
epadmin servicename=A.sbuser start node
```
Anytime afterwards, you can use the load secret command to install the secret into the stopped or running node. The stopped or running node is known to have no encrypted configuration values, or it would not have installed without specifying a secret key at install time. You can use load secret anytime after the node is installed, but before uploading any new configuration files with encrypted values. For example:
```
epadmin --servicename=A.sbuser load secret 
    --keystore=/full/path/to/lockbox
    --keystorepassword=secretive
```
For security safety:
- This command fails if a key is already loaded into this node.
- You can only load a key into a node one time.
Next, you can upload and activate replacement configuration files that this time have values encrypted with the same secret key specified in the load secret command. To do this, you must stop the node, or at least stop the engine that the replacement files configure. For example:
```
epadmin --servicename=engineNameInA.sbuser stop engine
epadmin --servicename=A.sbuser load configuration 
    --source=confWithEncryptedValues.conf ...
epadmin --servicename=A.sbuser activate configuration 
    --type=... --name=... --version=2
epadmin --servicename=engineNameInA.sbuser start engine
```
Make sure your replacement configuration files have a different name and/or version value for the same type, so that you can specify which version to activate.

Restarting the engine, or restarting the node that contains the engines, decrypts all encrypted configuration values.
As a best practice, you can now remove the original configuration files from shared memory by specifying their name and/or version. This avoids the possibility of inadvertently reactivating configurations with unencrypted data, and prevents anyone from seeing the unencrypted passwords or other sensitive data by means of an epadmin display configuration or export configuration command.
```
epadmin --servicename=A.sbuser remove configuration 
    --type=... --name=... --version=1
```

The Master Secret Key

Master secret keys are created when you install a node, and that node's key decrypts all encrypted values in all configuration files for all of that node's fragments. The node does not need to exist before creating its master secret and encrypting secure data with it. The keystore is simply a structured file, encrypted with a password. The node owner who runs the epadmin install node command does need to be on the same machine as any node in order to create and use a master secret.

You can also specify a master secret after you install a node, using the epadmin load secret command, as discussed in the previous section. You must provide the path to a keystore file and its password on the command line (or be prompted for the password), and the node stores the key in the node.

You are free to share the keystore file and its password with trusted colleagues who may be developing modules for your StreamBase Application whose configuration files have encryptable configuration values. The keystore file by itself cannot be used to decrypt anything. Users of the epadmin encrypt secret command do not need to be on the machine that first created the secret.

Once installed in or uploaded to a node, the node stores the encrypted secret in unencrypted form in the node directory. The secret file in the node directory has permissions such that only the node owner can read the file, and no other users have any permissions on the file. The node owner is the operating system user who runs the install node command and owns the node directory. The file is stored, highly protected, in unencrypted form in order to allow unattended operation of the node.

Until a master secret is provided to the node, any attempt to activate node configurations containing encrypted secure data fails. This includes any attempt to install the node, or start engines in the node, which activates configurations.

Protecting Key Files

The secret cannot be changed once set on a node, because then it would be unable to decrypt secure data encrypted with a prior master secret. Any attempt to use the epadmin load secret command on a node with an existing master secret fails.

If the master secret file is removed from the node directory, then the node can no longer decrypt any encrypted secure data. For this to happen, the node owner would have to change the file permissions on the disk and then delete the file. Thus, it is possible, but would require malicious intent and effort.

It is possible to recover from a deleted master secret file situation by using epadmin load secret to load the same master secret from its original keystore. If the keystore is not available, then you must generate a new master secret and load and activate new versions of all configurations containing secure data encrypted with the new secret. Depending on whether such files need to be active in order for node administration authentication and authorization to work, the node may not be administrable and may need to be recreated.

Encrypting Strings

Once you create the secret in its keystore, you are free to encrypt sensitive data using the epadmin encrypt secret command. This command takes the path to the keystore file, the keystore's password, and the data to encrypt. It retrieves the master secret from the keystore and uses it to encrypt the requested data. The result is a text string output to standard output, prefixed with an encryption indicator. That text can then be pasted into any HOCON configuration file prior to loading it into a node.

For example, to encrypt the password s3KriTly for an adapter connection specified in a configuration file:

epadmin encrypt secret --keystore=/full/path/to/lockbox 
    --keystorepassword=secretive --data=s3KriTly

Decrypting Encrypted Strings

Once a master secret is installed on a node, the StreamBase Runtime uses the secret to decrypt any string prefaced with an encryption indicator. The Runtime recognizes an encrypted string by the encryption indicator in its first few characters:

Encryption Indicator	Encrypted By
`#!!`	epadmin encrypt secret
`#!`	sbcipher (deprecated; do not use)

See Backward Compatibility for more on support for decrypting deprecated sbcipher strings.

Encryptable Configuration Properties

You can encrypt the following properties in HOCON configuration files. Configuration files are described in more detail in the Configuration Guide.

LDAP Authentication Realm

systemPassword

Local Authentication Realm

password

Open ID Connect Authentication Realm

clientSecret

Secure Communication Client Profile

keyStorePassword

keyPassword

trustStorePassword

Secure Communication Server Profile

keyStorePassword

keyPassword

trustStorePassword

EventFlow JMS or TIBCO EMS Adapter

password

EventFlow JDBC Data Source Group

serverURL

userName

password

additionalDriverArguments

LiveView Engine Internal Credentials

ldmInternalPassword

streamBaseAdminPassword

streamBasePassword

EventFlow Engine

constantsOverwrite

operatorParameters

ParameterSettingsGroup

parameter names

Cluster Monitor

administrationAuthentication: password

eventFlowAuthentication: password

Backward Compatibility and Deprecation

The StreamBase 10 Runtime continues to be able to decrypt data obfuscated with the sbcipher tool, which was deprecated as of StreamBase release 10.3.0. This support allows you to copy an sbcipher-encrypted string such as a password from a StreamBase 7 sbconf XML file into a StreamBase 10 HOCON configuration file, and have the string decrypted automatically at runtime.

Every StreamBase 10 node must have a master secret installed in order to decrypt either encrypted string type. However, this backward compatibility is for decrypting strings only. Do not continue to use sbcipher to encrypt strings; instead use epadmin encrypt secret. Support for decrypting sbcipher-encrypted strings may be removed from a future release.

StreamBase 7 used public master secret files stored in STREAMBASE_HOME/etc to support decryption. The StreamBase 10 Runtime embeds the same keys internally to allow continued sbcipher decryption.

If your organization used alternative custom keys in StreamBase 7, you must copy those keys to a local file system location and point to them with a streambase.security.key-file entry in the systemProperties object in an engine configuration file. Contact Support for assistance with this advanced case. It is likely to be much easier to re-encrypt the same strings with epadmin encrypt secret than to continue to enable advanced sbcipher decryption.

Encrypting Sensitive Configuration Data

Overview

Note

Note

Using the load secret Command

The Master Secret Key

Protecting Key Files

Encrypting Strings

Decrypting Encrypted Strings

Encryptable Configuration Properties

Backward Compatibility and Deprecation