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.

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.

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.

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.8.jar or corda-tools-config-obfuscator-4.8.jar).

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]

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 to DEFAULT. 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.

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> are ERROR (default), WARN, INFO, DEBUG, and TRACE.
  • -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.

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.8.jar install-shell-extensions

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.8.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.8.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):
p2pAddress="localhost:10005"
rpcSettings {
  address="localhost:10006"
  adminAddress="localhost:10015"
}
security {
  authService {
    dataSource {
      type=INMEMORY
      users=[
        {
          password="<encrypt{my-pass}>"
          permissions=[
            ALL
          ]
          user=bankUser
        }
      ]
    }
  }
}

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
$ export CONFIG_OBFUSCATION_SEED=my-seed; export CONFIG_OBFUSCATION_PASSPHRASE=my-passphrase; java -jar tools/config-obfuscator/build/libs/corda-tools-config-obfuscator-4.8.jar -w node.conf /p/tmp/node-non-obfuscated.conf

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.

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):
$ export CONFIG_OBFUSCATION_SEED=my-seed; export CONFIG_OBFUSCATION_PASSPHRASE=my-passphrase; java -jar corda.jar

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"
  },
  // (...)
}

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}>",
  // (...)
}

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==}>",
  // (...)
}

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",
  // (...)
}

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.