Apache
/
nifi
mirror of https://github.com/apache/nifi.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

NIFI-2451 Added new documentation regarding encrypt-config tool after changes in NIFI-1831.

This commit is contained in:
Andy LoPresto 2016-08-23 21:54:53 -07:00
parent 5c07e681b4
commit b9a04ea045
No known key found for this signature in database
GPG Key ID: 3C6EF65B2F7DEF69
1 changed files with 36 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
nifi-docs/src/main/asciidoc/administration-guide.adoc
View File

@ -970,7 +970,7 @@ It is preferable to request upstream/downstream systems to switch to https://cwi
Encrypted Passwords in Configuration Files
------------------------------------------
In order to facilitate the secure setup of NiFi, you can use the encrypt-config command line utility to encrypt raw configuration values that NiFi decrypts in memory on startup. This extensible protection scheme transparently allows NiFi to use raw values in operation, while protecting them at rest. In the future, hardware security modules (HSM) and external secure storage mechanisms will be integrated, but for now, an AES encryption provider is the default implementation.
In order to facilitate the secure setup of NiFi, you can use the `encrypt-config` command line utility to encrypt raw configuration values that NiFi decrypts in memory on startup. This extensible protection scheme transparently allows NiFi to use raw values in operation, while protecting them at rest. In the future, hardware security modules (HSM) and external secure storage mechanisms will be integrated, but for now, an AES encryption provider is the default implementation.
This is a change in behavior; prior to 1.0, all configuration values were stored in plaintext on the file system. POSIX file permissions were recommended to limit unauthorized access to these files
@ -980,17 +980,20 @@ If no administrator action is taken, the configuration values remain unencrypted
Encrypt-Config Tool
~~~~~~~~~~~~~~~~~~~
The encrypt-config command line tool reads from a 'nifi.properties' file with plaintext sensitive configuration values, prompts you for a master key, and encrypts each value. It replaces the plain values with the protected value in the same file, or writes to a new 'nifi.properties' file if specified.
The `encrypt-config` command line tool (invoked as `./bin/encrypt-config.sh` or `bin\encrypt-config.bat`) reads from a 'nifi.properties' file with plaintext sensitive configuration values, prompts for a master password or raw hexadecimal key, and encrypts each value. It replaces the plain values with the protected value in the same file, or writes to a new 'nifi.properties' file if specified.
The default encryption algorithm utilized is AES/GCM 128/256-bit. 128-bit is used if JCE Unlimited Strength Crypto Policy is not installed, and 256-bit is used if it is installed.
The default encryption algorithm utilized is AES/GCM 128/256-bit. 128-bit is used if the JCE Unlimited Strength Cryptographic Jurisdiction Policy files are not installed, and 256-bit is used if they are installed.
You can use the following command line options with the encrypt-config tool:
* -b (or --bootstrapConf) Specifies the bootstrap.conf file you want to use to persist the master key.
* -h (or --help) Prints the usage message.
* -k (or --hexKey) The raw hexadecimal key to use to encrypt the sensitive properties. Must be a 32 or 64 hexadecimal string. Some basic error handling is performed if the string is not formatted properly.
* -n (or --niFiProperties) The nifi.properties file containing unprotected config values. The input nifi.properties file is overwritten.
* -o (or --outputNiFiProperties) The destination nifi.properties file containing protected config values. The input nifi.properties file is not modified.
* `-b,--bootstrapConf <arg>` The bootstrap.conf file to persist master key
* `-h,--help` Prints this usage message
* `-k,--key <arg>` The raw hexadecimal key to use to encrypt the sensitive properties (the key can be entered with spaces or '-' delimiters to assist manual entry -- these will be ignored)
* `-n,--niFiProperties <arg>` The nifi.properties file containing unprotected config values (will be overwritten by default unless `-o` is provided)
* `-o,--outputNiFiProperties <arg>` The destination nifi.properties file containing protected config values (will not modify input nifi.properties)
* `-p,--password <arg>` The password from which to derive the key to use to encrypt the sensitive properties
* `-r,--useRawKey` If provided, the secure console will prompt for the raw key value in hexadecimal form
* `-v,--verbose` Sets verbose mode (default false)
As an example of how the tool works, assume that you have installed the tool on a machine supporting 256-bit encryption and with the following existing values in the 'nifi.properties' file:
@ -1019,7 +1022,7 @@ encrypt-config.sh
-n nifi.properties
----
As a result, the 'nifi.properties' file is overwritten with protected properties and sibling encryption identifiers (aes/gcm/256, the currently supported algorithm):
As a result, the 'nifi.properties' file is overwritten with protected properties and sibling encryption identifiers (`aes/gcm/256`, the currently supported algorithm):
----
# security properties #
@ -1051,6 +1054,30 @@ Sensitive configuration values are encrypted by the tool by default, however you
If the 'nifi.properties' file already has valid protected values, those property values are not modified by the tool.
[[encrypt-config_password]]
Password Key Derivation
~~~~~~~~~~~~~~~~~~~~~~~
Instead of providing a 32 or 64 character raw hexadecimal key, the user can provide a password from which the key will be derived. As of 1.0.0, the password must be at least 12 characters, and the key will be derived using `SCrypt` with the parameters:
* `pw` -- the password bytes in `UTF-8`
* `salt` -- the fixed salt value (`NIFI_SCRYPT_SALT`) bytes in `UTF-8` _see note below_
* `N` -- 2^16^
* `r` -- 8
* `p` -- 1
* `dkLen` -- determined by the JCE policies available
These values are determined to be strong for this threat model in August 2016 but may change in future versions.
_Note:_
While fixed salts are counter to best practices, a static salt is necessary for deterministic key derivation without additional storage of the salt value.
[[encrypt-config_secure_prompt]]
Secure Prompt
~~~~~~~~~~~~~
For users who prefer not to provide the password or raw key in the command-line invocation of the tool, leaving these arguments absent will prompt a secure console read of the password (by default) or raw key (if the `-r` flag is provided at invocation).
[[clustering]]
Clustering Configuration
------------------------