Overview

MiNiFi can encrypt sensitive values in its configuration files in three ways:

  1. Encrypt the value of sensitive properties in the minifi.properties file;
  2. Encrypt the value of sensitive properties in the config.yml flow definition file;
  3. Encrypt the contents of the config.yml file as a whole.

Some of this encryption happens automatically, some can be enabled manually, and some are done manually (see below for the details). Automatic encryption is done by MiNiFi as it runs, and manual encryption is done using the encrypt-config tool (encrypt-config.exe on Windows) which can be found in the bin directory of the installation, next to the main minifi (minifi.exe) binary.

In all three cases, the security of the encryption depends on the security of the bootstrap.conf file, which contains the encryption key. Make sure that only authorized users are able to read this file.

Vocabulary

  • minifi home: the directory which contains MiNiFi configuration files (in the conf subdirectory), as well as the logs and other files used by MiNiFi
  • configuration directory: the directory <minifi home>/conf
  • properties file: the file <minifi home>/conf/minifi.properties
  • flow configuration file: the file specified in the properties file with the key nifi.flow.configuration.file, or if not specified it defaults to <minifi home>/conf/config.yml
  • bootstrap file: the file <minifi home>/conf/bootstrap.conf
  • sensitive value: all values in the properties file and the flow configuration file that we wish to encrypt

1. Encrypt sensitive values in minifi.properties

The sensitive values in the properties file can be encrypted manually, using the encrypt-config tool.

For example, if you have a minifi.properties file in your MiNiFi configuration directory /opt/minifi-home/conf containing the following sensitive properties:

minifi.properties
...
nifi.security.client.pass.phrase=my_pass_phrase
...
nifi.rest.api.user.name=admin
nifi.rest.api.password=password123
...

you can run the encrypt-config tool like this:

$ ./bin/encrypt-config --minifi-home /opt/minifi-home minifi-properties

Generating a new encryption key...
Wrote the new encryption key to /opt/minifi-home/conf/bootstrap.conf
Encrypted property: nifi.security.client.pass.phrase
Encrypted property: nifi.rest.api.password
Encrypted 2 sensitive properties in /opt/minifi-home/conf/minifi.properties

which will

  1. Generate a new encryption key
  2. Create a bootstrap.conf file in your configuration directory, and write the encryption key to this file
  3. Encrypt the sensitive values using this encryption key
  4. Add a <property_name>.protected encryption marker after each encrypted property.

After running the tool, bootstrap.conf will look like this:

bootstrap.conf
nifi.bootstrap.sensitive.key=77cd3f88ab997f7ae99b13c70877c5274c3b7b495f601f290042b14e7db4d542

and minifi.properties will look like this:

minifi.properties
...
nifi.security.client.pass.phrase=STBmfU0uk5hgSYG5O3uJM3HeZjrYJz//||vE/V65QiMgSatzScaPYkraVrpWnBExVgVX/CwyXx
nifi.security.client.pass.phrase.protected=xsalsa20poly1305
...
nifi.rest.api.user.name=admin
nifi.rest.api.password=q8XNjJMoVABXz7sks5O6nhaTqqRay4gF||U3762djgMVguHI6GjRl+iCCDSkIdTFzKDCXi
nifi.rest.api.password.protected=xsalsa20poly1305
...

Additional sensitive properties

By default, encrypt-config will encrypt a (short) list of default sensitive properties.  If you want more properties to be encrypted, you can add a nifi.sensitive.props.additional.keys setting with a comma-separated list of additional sensitive properties to your minifi.properties file like this:

minifi.properties
...
nifi.sensitive.props.additional.keys=nifi.rest.api.user.name,controller.socket.host,controller.socket.port
...

before running the encrypt-config tool.  The tool will then encrypt these additional properties, as well.  You can also do this after you have already encrypted some properties; the tool will encrypt the additional properties using the existing encryption key, and it will leave the other, already encrypted, sensitive properties alone.

Modifying sensitive properties

If you later need to modify the value of a sensitive property which was encrypted earlier, you need to:

  1. Replace the encrypted value with the new, unencrypted value
  2. Delete the "something.protected=..." line which was added by the tool
  3. Re-run the encrypt-config tool.

The tool will then encrypt the modified property value using the existing encryption key in bootstrap.conf, and it will leave the other, already encrypted, sensitive properties alone.

2. Encrypt sensitive values in config.yml

The sensitive properties of processors and controller services in the flow definition file config.yml are encrypted by MiNiFi automatically. For example, if the flow configuration comes from a C2 server, MiNiFi will encrypt the sensitive property values before saving them to the config.yml file. If you write or modify the config.yml file by hand, you have two options:

  • Write the sensitive values unencrypted into the file, then (re)start MiNiFi. MiNiFi will read the new values, encrypt them, and write the encrypted values back to the file.
  • If you want to avoid having the sensitive values unencrypted on disk even for a short time, you can use the encrypt-config tool to write these values directly to config.yml in encrypted form.

To do the latter, you have two options: either run

$ ./bin/encrypt-config --minifi-home /opt/minifi-home flow-config

which will read the flow configuration file, find the sensitive properties, and prompt you to either enter a new value for the sensitive property, or press Enter to keep its value unchanged.

Or, if you know the unique ID of the component (processor of controller service) and the name of the sensitive property, or if you are running encrypt-config from a script, you can set or update a single sensitive property like this:

$ ./bin/encrypt-config --minifi-home /opt/minifi-home flow-config --component-id <COMPONENT_ID> --property-name <PROPERTY_NAME> --property-value <NEW_VALUE>

In all cases, either MiNiFi or encrypt-config will create a new encryption key if one doesn't exist already, and store it in the bootstrap.conf file:

bootstrap.conf
nifi.bootstrap.sensitive.properties.key=6bdb53d024993c6ce06c0851af2758ddfc53fc784047d983b816cdc7ff4bc37d

Note that the name of the key is different from the key used to encrypt minifi.properties.

3. Encrypt the config.yml file as a whole

If you want to encrypt more than just the properties considered sensitive by MiNiFi in the config.yml file, you can encrypt the file as a whole in addition to the encryption of the sensitive properties which happens automatically. You have two options:

  1. Set nifi.flow.configuration.encrypt=true in the minifi.properties file. When MiNiFi receives a new flow configuration from a C2 server, it will encrypt the configuration as a whole, and write it encrypted to config.yml.

  2. Or run

    $ ./bin/encrypt-config --minifi-home /opt/minifi-home whole-flow-config-file

    manually.

In both cases, you can either add the nifi.bootstrap.sensitive.key setting to the bootstrap file manually, or a random key will be generated for you.

Updating the encryption key

If you have write access to the bootstrap.conf file, you can change the encryption key as follows:

For minifi.properties and whole-flow-config-file encryption

  1. Change the nifi.bootstrap.sensitive.key=... line in bootstrap.conf to nifi.bootstrap.sensitive.key.old=... (i.e. add the ".old" suffix);
  2. If you have a specific encryption key you would like to use, add it to the bootstrap.conf file (add the line nifi.bootstrap.sensitive.key=<your encryption key here>). If you provide no new encryption key, one will be randomly generated for you;
  3. Run the encrypt-config tool for the type of encryption you need, or both;
  4. Finally, delete the nifi.bootstrap.sensitive.key.old line from the bootstrap file.

Example:

$ cat /opt/minifi-home/conf/bootstrap.conf
nifi.bootstrap.sensitive.key.old=0728061a041edb09445ae4dbd95f11bd255bb0b467b8efb239e665aea5ace46b

$ ./bin/encrypt-config --minifi-home /opt/minifi-home minifi-properties
Old encryption key found in "/opt/minifi-home/conf/bootstrap.conf"
Generating a new encryption key...
Wrote the new encryption key nifi.bootstrap.sensitive.key to "/opt/minifi-home/conf/bootstrap.conf"
Successfully decrypted property "nifi.security.client.pass.phrase" using old key.
Encrypted property: nifi.security.client.pass.phrase
Encrypted 1 sensitive property in "/opt/minifi-home/conf/minifi.properties"
WARNING: an .old key was provided, which is used for both minifi-properties and whole-flow-config-file.
If both are currently encrypted, make sure to run ./bin/encrypt-config to re-encrypt both before removing the .old key,
otherwise you won't be able to recover the encrypted data!

$ ./bin/encrypt-config --minifi-home /opt/minifi-home whole-flow-config-file
Old encryption key found in "/opt/minifi-home/conf/bootstrap.conf"
Using the existing encryption key nifi.bootstrap.sensitive.key found in "/opt/minifi-home/conf/bootstrap.conf"
Encrypting flow configuration file: "/opt/minifi-home/conf/config.yml"
Trying to decrypt flow config file using the old key ...
Successfully encrypted flow configuration file: "/opt/minifi-home/conf/config.yml"
WARNING: an .old key was provided, which is used for both minifi-properties and whole-flow-config-file.
If both are currently encrypted, make sure to run ./bin/encrypt-config to re-encrypt both before removing the .old key,
otherwise you won't be able to recover the encrypted data!

$ cat /opt/minifi-home/conf/bootstrap.conf
nifi.bootstrap.sensitive.key.old=0728061a041edb09445ae4dbd95f11bd255bb0b467b8efb239e665aea5ace46b
nifi.bootstrap.sensitive.key=46af2c11a3f24c8c875ab4bee65e18a75f825fc3a4e03abdc8ce49d405b0b730

Since both the sensitive values in minifi.properties and the whole config.yml file are encrypted using the same key, it is important to always run encrypt-config on both, if both encryptions are used. The encrypt-config tool reminds you of this in a warning message it prints.

For sensitive properties in config.yml

This encryption uses a different key from the other two, but the procedure is very similar:

  1. Change the nifi.bootstrap.sensitive.properties.key=... line in bootstrap.conf to nifi.bootstrap.sensitive.properties.key.old=... (i.e. add the ".old" suffix);
  2. If you have a specific encryption key you would like to use, add it to the bootstrap.conf file (add the line nifi.bootstrap.sensitive.properties.key=<your encryption key here>). If you provide no new encryption key, one will be randomly generated for you;
  3. Run the encrypt-config tool with the flow-config --re-encrypt arguments;
  4. Finally, delete the nifi.bootstrap.sensitive.properties.key.old line from the bootstrap file.

Example:

$ cat /opt/minifi-home/conf/bootstrap.conf
nifi.bootstrap.sensitive.properties.key.old=6bdb53d024993c6ce06c0851af2758ddfc53fc784047d983b816cdc7ff4bc37d

$ ./bin/encrypt-config --minifi-home /opt/minifi-home flow-config --re-encrypt
Old encryption key found in "/opt/minifi-home/conf/bootstrap.conf"
Generating a new encryption key...
Wrote the new encryption key nifi.bootstrap.sensitive.properties.key to "/opt/minifi-home/conf/bootstrap.conf"
Encrypting flow configuration file: "/opt/minifi-home/conf/config.yml"
[2024-03-04 18:31:19.764] [org::apache::nifi::minifi::Properties] [info] Using configuration file to load configuration for MiNiFi configuration from conf/minifi.properties (located at /opt/minifi-home/conf/minifi.properties)
[2024-03-04 18:31:19.892] [org::apache::nifi::minifi::core::FlowConfiguration] [info] Result of updating the config file /opt/minifi-home/conf/config.yml: success

$ cat /opt/minifi-home/conf/bootstrap.conf
nifi.bootstrap.sensitive.properties.key.old=6bdb53d024993c6ce06c0851af2758ddfc53fc784047d983b816cdc7ff4bc37d
nifi.bootstrap.sensitive.properties.key=ea55b7d0edc22280c9547e4d89712b3fae74f96d82f240a004fb9fbd0640eec7
  • No labels