Configuration Obfuscator
The purpose of the Configuration Obfuscator tool is to obfuscate sensitive information in configuration files.
The Configuration Obfuscator makes node installation less vulnerable to someone trawling plain text files, searching for passwords and credentials of resources that they should not have access to in the first place.
How obfuscation works
You obfuscate a configuration file using the Configuration Obfuscation tool. In the example below, the user
and password
properties are encrypted by placing them in this format: "<encrypt{your-secret-database-password}>"
.
{
// (...)
"dataSourceProperties" : {
"dataSource" : {
"url" : "jdbc:h2:file:persistence;<encrypt{sensitive-options-go-here}>",
"user" : "<encrypt{your-database-username}>",
"password" : "<encrypt{your-secret-database-password}>"
},
"dataSourceClassName" : "org.h2.jdbcx.JdbcDataSource"
},
// (...)
}
The tool takes a seed and a passphrase as input to obfuscate a given configuration file.
How deobfuscation works
You deobfuscate an obfuscated configuration file by starting the respective node, Firewall component, or service (for example, a Corda Enterprise Network Manager service).
You cannot use the Configuration Obfuscator tool to deobfuscate an obfuscated file directly. This is intentional in order to prevent a potential security risk where plain text passwords could be revealed by just running the tool again.
The node or service itself deobfuscates the configuration object internally on startup, taking the same seed and passphrase as the Configuration Obfuscator tool. The ‘Deobfuscate an obfuscated configuration file’ section further below describes how to do that.
Obfuscate using the command-line tool
The command-line tool is included in Corda Enterprise as a JAR file with a name corda-tools-config-obfuscator-<version>.jar
, where <version>
stands for the Corda Enterprise version (for example, corda-tools-config-obfuscator-4.9.jar
or corda-tools-config-obfuscator-4.9.jar
).
Usage
The parameters, options, and commands that you can use when running the command-line tool, are shown below.
config-obfuscator [-hiV] [--config-obfuscation-passphrase[=<cliPassphrase>]]
[--config-obfuscation-seed[=<cliSeed>]] [-w[=<writeToFile>]]
[--logging-level=<loggingLevel>] CONFIG_FILE
[HARDWARE_ADDRESS]
Input parameters
The command-line tool takes following parameters as input:
CONFIG_FILE
is the name of the configuration file to obfuscate. This is a mandatory parameter.--config-obfuscation-passphrase[=<cliPassphrase>]
is the passphrase used in the key derivation function when generating an AES key. Leave blank to provide input interactively.--config-obfuscation-seed[=<cliSeed>]
is the seed used in the key derivation function to create a salt. Leave blank to provide input interactively.[HARDWARE_ADDRESS]
is the primary hardware address of the machine on which the configuration file resides. By default, the MAC address of the running machine is used - to explicitly use that, set the value toDEFAULT
. Note that this parameter provides backwards compatibility but should not be used in cases where backwards compatibility is not required. This is an optional parameter.
Input options
The following options are available when running the command-line tool:
-v, --verbose, --log-to-console
is an option to print logging to the console as well as to a file.--logging-level=<loggingLevel>
is an option to enable logging at this level or higher. The possible values for<loggingLevel>
areERROR
(default),WARN
,INFO
,DEBUG
, andTRACE
.-w=[<writeToFile>]
is a flag to indicate that the tool should write the obfuscated output to disk, using the same file name as the input (if left blank and provided at the end of the command line), or the provided file name.-i
is a flag, which if set, says to provide input to obfuscated fields interactively.-h
,--help
is a flag used to show this help message and exit.-V
,--version
is a flag used to print version information and exit.
By default, the command-line tool only prints out the transformed configuration to the terminal for verification. To persist the changes, you must use the -w
flag, which ensures that the obfuscated content gets written back into the provided configuration file.
The -w
flag also takes an optional file name for cases where you need to write the result back to a different file. If you are not providing the optional file name, you must put the -w
flag at the end of the command.
An example of these two cases follows below:
# Explicit output file provided
$ java -jar corda-tools-config-obfuscator-4.9.jar -w node.conf node_template.conf
# No output file provided
$ java -jar corda-tools-config-obfuscator-4.9.jar node_template.conf -w
Input commands
You can use the following command to install ‘alias’ and ‘autocompletion’ for bash
and zsh
:
install-shell-extensions
For example:
$ java -jar corda-tools-config-obfuscator-4.9.jar install-shell-extensions
How to pass the seed and passphrase to the Obfuscation Tool using the command-line tool options
As described above, the command-line tool takes a seed and a passphrase as input parameters, and uses them to derive a 256bit AES encryption key.
- The option (flag) for the seed is
--config-obfuscation-seed[=<cliSeed>]
. - The option (flag) of the passphrase is
--config-obfuscation-passphrase[=<cliPassphrase>]
.
If you provide a value in your command, that value is treated as the seed/passphrase. Otherwise, you are prompted to provide the seed/passphrase in the command prompt.
The following example shows a run of the command-line tool with a seed and a passphrase passed explicitly:
$ java -jar tools/config-obfuscator/build/libs/corda-tools-config-obfuscator-4.9.jar --config-obfuscation-seed my-seed --config-obfuscation-passphrase my-passphrase -w node.conf /p/tmp/node-non-obfuscated.conf
The following example shows a run of the command-line tool with the seed and passphrase values left blank - the user is prompted to provide these interactively:
$ java -jar tools/config-obfuscator/build/libs/corda-tools-config-obfuscator-4.9.jar --config-obfuscation-seed --config-obfuscation-passphrase -w node.conf /p/tmp/node-non-obfuscated.conf
$ Enter value for --config-obfuscation-seed (The seed used in the key derivation function to create a salt):
$ Enter value for --config-obfuscation-passphrase (The passphrase used in the key derivation function when creating an AES key):
Example of an obfuscated node configuration file
p2pAddress="localhost:10005"
rpcSettings {
address="localhost:10006"
adminAddress="localhost:10015"
}
security {
authService {
dataSource {
type=INMEMORY
users=[
{
password="<encrypt{my-pass}>"
permissions=[
ALL
]
user=bankUser
}
]
}
}
}
Obfuscate using environment variables
Another way to provide the seed and passphrase to obfuscate a configuration file is to set the following environment variables:
CONFIG_OBFUSCATION_SEED
CONFIG_OBFUSCATION_PASSPHRASE
How to pass the seed and passphrase to the Obfuscation Tool using environment variables
$ export CONFIG_OBFUSCATION_SEED=my-seed; export CONFIG_OBFUSCATION_PASSPHRASE=my-passphrase; java -jar tools/config-obfuscator/build/libs/corda-tools-config-obfuscator-4.9.jar -w node.conf /p/tmp/node-non-obfuscated.conf
Deobfuscate an obfuscated configuration file
You deobfuscate an obfuscated configuration file by starting the respective node, Firewall component, or service (for example, a Corda Enterprise Network Manager service).
When you need your node, Firewall component, or service, to deobfuscate an obfuscated configuration file, you must pass them the same seed and passhprase used when that configuration file was deobfuscated. There are two ways you can do that, as described below.
How to pass the seed and passphrase to a node, Firewall component, or service, using the command-line tool options
To pass the obfuscation seed and passphrase to a node or Firewall component using the command-line tool, use the --config-obfuscation-seed
and --config-obfuscation-passphrase
flags, respectively, in your node, Firewall, or service run command.
These flags are the same for all components that use the Configuration Obfuscator tool.
The following example shows how to pass a seed and a passphrase explicitly to a node component using the command-line tool:
$ java -jar corda.jar --config-obfuscation-seed my-seed --config-obfuscation-passphrase my-passphrase
The following example shows how to pass a seed and a passphrase to a node component using the command-line tool by leaving the flag values blank to invoke a prompt:
$ java -jar corda.jar --config-obfuscation-seed --config-obfuscation-passphrase
$ Enter value for --config-obfuscation-seed (The seed used in the key derivation function to create a salt):
$ Enter value for --config-obfuscation-passphrase (The passphrase used in the key derivation function when creating an AES key):
Pass the seed and passphrase to a node, Firewall component, or service, using environment variables
$ export CONFIG_OBFUSCATION_SEED=my-seed; export CONFIG_OBFUSCATION_PASSPHRASE=my-passphrase; java -jar corda.jar
Configuration directives
The configuration directives described below can be placed arbitrarily within ‘string’ properties in the target configuration file, with a maximum of one per line.
For example:
{
// (...)
"dataSourceProperties" : {
"dataSource" : {
"url" : "jdbc:h2:file:persistence;<encrypt{sensitive-options-go-here}>",
"user" : "<encrypt{your-database-username}>",
"password" : "<encrypt{your-secret-database-password}>"
},
"dataSourceClassName" : "org.h2.jdbcx.JdbcDataSource"
},
// (...)
}
Directive to indicate obfuscation areas
To indicate parts of the configuration that should be obfuscated, you can place text markers in the form <encrypt{...}>
. For example:
{
// (...)
"p2pAddress": "somehost.com:10001",
"keyStorePassword": "<encrypt{testpassword}>",
// (...)
}
If your configuration file uses include
directives, as shown below, then the referenced file is automatically imported and obfuscated with the main file. The result will contain both the main file and the include
file in the output:
include "path/to/file.conf"
include required("path/to/file.conf")
Each include
statement must be on a single line and follow the format shown above.
The example below shows how this area of the configuration file will look like after it is run through the obfuscation tool:
{
// (...)
"p2pAddress": "somehost.com:10001",
"keyStorePassword": "<{8I1E8FKrBxVkRpZGZKAxKg==:oQqmyYO+SZJhRkPB7laNyQ==}>",
// (...)
}
Deobfuscation based on configuration directives
When the Corda node, Firewall component, or service is run with the correct seed/passphrase provided, the configuration is deobfuscated on the fly and interpreted as shown in the example below:
{
// (...)
"p2pAddress": "somehost.com:10001",
"keyStorePassword": "testpassword",
// (...)
}
Limitations
The <encrypt{}>
blocks can only appear inside ‘string’ properties - they cannot be used to obfuscate entire configuration blocks.
Otherwise, the Corda node or service will not be able to decipher the obfuscated content.
More explicitly, this means that the blocks can only appear on the right-hand side of the colon, and for ‘string’ properties only.
Was this page helpful?
Thanks for your feedback!
Chat with us
Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
Propose documentation improvements directly
Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.
We're sorry this page wasn't helpful. Let us know how we can make it better!
Chat with us
Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
Create an issue
Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.
Propose documentation improvements directly
Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.