Overview
MiNiFi can encrypt sensitive values in its configuration files in three ways:
- Encrypt the value of sensitive properties in the
minifi.properties
file; - Encrypt the value of sensitive properties in the
config.yml
flow definition file; - 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: 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:
... 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
- Generate a new encryption key
- Create a
bootstrap.conf
file in your configuration directory, and write the encryption key to this file - Encrypt the sensitive values using this encryption key
- Add a
<property_name>.protected
encryption marker after each encrypted property.
After running the tool, bootstrap.conf
will look like this:
nifi.bootstrap.sensitive.key=77cd3f88ab997f7ae99b13c70877c5274c3b7b495f601f290042b14e7db4d542
and minifi.properties
will look like this:
... 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:
... 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:
- Replace the encrypted value with the new, unencrypted value
- Delete the "
something.protected=..."
line which was added by the tool - 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 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 toconfig.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:
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:
- Set
nifi.flow.configuration.encrypt=true
in theminifi.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 toconfig.yml.
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
- Change the
nifi.bootstrap.sensitive.key=...
line inbootstrap.conf
tonifi.bootstrap.sensitive.key.old=...
(i.e. add the ".old" suffix); - If you have a specific encryption key you would like to use, add it to the
bootstrap.conf
file (add the linenifi.bootstrap.sensitive.key=<your encryption key here>
). If you provide no new encryption key, one will be randomly generated for you; - Run the
encrypt-config
tool for the type of encryption you need, or both; - 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:
- Change the
nifi.bootstrap.sensitive.properties.key=...
line inbootstrap.conf
tonifi.bootstrap.sensitive.properties.key.old=...
(i.e. add the ".old" suffix); - If you have a specific encryption key you would like to use, add it to the
bootstrap.conf
file (add the linenifi.bootstrap.sensitive.properties.key=<your encryption key here>
). If you provide no new encryption key, one will be randomly generated for you; - Run the
encrypt-config
tool with theflow-config --re-encrypt
arguments; - 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