Encrypting Sensitive Configuration Data

StreamBase HOCON configuration files might store sensitive data like passwords, 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 key store file. The key store is in turn encrypted with a user-specified password.

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

The node does not need to exist before creating its master secret and encrypting secure data with it, nor does the user need to be on the same machine as any node in order to create and use a master secret. The key store is simply a structured file, encrypted with a password, and can be loaded later into any node.

Once the secret is created and placed in the encrypted key store, you can create a node that uses that secret to decrypt the encrypted sensitive data in any HOCON configuration files activated on the node. The secret can be provided to the node at node install time, or at any time afterward. If provided at install time, you supply a key store and password on the node install command line, or epadmin prompts for the password if not on the command line. The node then stores the secret in a clear text file in the node directory. The file has permissions such that the operating system user owning the node directory can only read the file, and no other users have any permissions on the file. The file is stored, highly protected, as clear text in order to permit unattended operation of the node.

You can also specify a master secret after you install a node, using the epadmin load secret command. Again you must provide a key store and password on the command line (or be prompted for the password), and the node stores the secret as above.

Once a master secret is installed on a node, the node uses it to decrypt any data prefaced with an encryption indicator. The output of epadmin encrypt secret is prefaced with the #!! indicator, while the output of the deprecated sbcipher tool is prefaced with #!. Until a master secret is provided to the node, any attempt to activate node configurations containing encrypted secure data fails.

The secret cannot be changed once set on the 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 clear text 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 the deleted master secret file situation by using epadmin load secret to load the same master secret from its original key store. If the key store 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.

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

StreamBase continues to be able to decrypt data obfuscated with the sbcipher tool, which is now deprecated. See the Enciphering page of the Administration Guide of previous StreamBase 10.x releases for guidance on using this command.

This includes data obfuscated with custom key pairs specified by the sbcipher streambase.security.key-file system property. To decrypt such data, you set this system property in the node's sbengine configuration file to be able to retrieve the clear text.