Apache/nifi
1
0
Fork 0
mirror of https://github.com/apache/nifi.git synced 2025-03-06 17:39:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

NIFI-13893 Removed Outdated Encryption Configuration from Admin Guide

Browse Source 
This closes #9414

- Removed unsupported sensitive properties algorithms
- Removed historical sensitive property provider configuration for bootstrap.conf

Signed-off-by: Joseph Witt <joewitt@apache.org>
This commit is contained in:
exceptionfactory 2024-10-17 14:25:09 -05:00 committed by Joseph Witt
parent f9fb4223a7
commit b719e8728e
No known key found for this signature in database
GPG Key ID: 9093BF854F811A1A
1 changed files with 1 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1815,14 +1815,8 @@ Each Key Derivation Function also uses default iteration and cost parameters as
=== Property Encryption Algorithms
The following strong encryption methods can be configured in the `nifi.sensitive.props.algorithm` property:
* `NIFI_ARGON2_AES_GCM_128`
* `NIFI_ARGON2_AES_GCM_256`
* `NIFI_BCRYPT_AES_GCM_128`
* `NIFI_BCRYPT_AES_GCM_256`
* `NIFI_PBKDF2_AES_GCM_128`
* `NIFI_PBKDF2_AES_GCM_256`
* `NIFI_SCRYPT_AES_GCM_128`
* `NIFI_SCRYPT_AES_GCM_256`
Each Key Derivation Function uses the following default parameters:
@ -1831,19 +1825,10 @@ Each Key Derivation Function uses the following default parameters:
** Memory: 65536 KB
** Parallelism: 8
* Bcrypt
** Cost: 12
** Derived Key Digest Algorithm: SHA-512
* PBKDF2
** Iterations: 160,000
** Pseudorandom Function Family: SHA-512
* Scrypt
** Cost Factor (N): 16384
** Block Size Factor (r): 8
** Parallelization Factor (p): 1
All options require a password (`nifi.sensitive.props.key` value) of *at least 12 characters*.
In new standalone installations of 1.14.0 or later, NiFi generates a random value when `nifi.sensitive.props.key` is
@ -1851,206 +1836,6 @@ empty. NiFi writes the generated value to `nifi.properties` and logs a warning.
Clustered installations of NiFi require the same value to be configured on all nodes.
[[hashicorp-vault-providers]]
=== HashiCorp Vault providers
Two encryption providers are currently configurable in the `bootstrap-hashicorp-vault.conf` file:
[options="header,footer"]
|===
|Provider|Provider Identifier|Description
|HashiCorp Vault Transit provider|`hashicorp/vault/kv/{vault.transit.path}`|Uses HashiCorp Vault's Transit Secrets Engine to decrypt sensitive properties.
|HashiCorp Vault Key/Value provider|`hashicorp/vault/kv/{vault.kv.path}`|Retrieves sensitive values from Secrets stored in a HashiCorp Vault Key/Value (unversioned) Secrets Engine.
|===
Note that all HashiCorp Vault encryption providers require a running Vault instance in order to decrypt these values at NiFi's startup.
Following are the configuration properties available inside the `bootstrap-hashicorp-vault.conf` file:
==== Required properties
[options="header,footer"]
|===
|Property Name|Description|Default
|`vault.uri`|The HashiCorp Vault URI (e.g., `https://vault-server:8200`). If not set, all HashiCorp Vault providers will be disabled.|_none_
|`vault.authentication.properties.file`|Filename of a properties file containing Vault authentication properties. See the `Authentication-specific property keys` section of https://docs.spring.io/spring-vault/docs/2.3.x/reference/html/#vault.core.environment-vault-configuration for all authentication property keys. If not set, all Spring Vault authentication properties must be configured directly in bootstrap-hashicorp-vault.conf.|_none_
|`vault.transit.path`|If set, enables the HashiCorp Vault Transit provider. The value should be the Vault `path` of a Transit Secrets Engine (e.g., `nifi-transit`). Valid characters include alphanumeric, dash, and underscore.|_none_
|`vault.kv.path`|If set, enables the HashiCorp Vault Key/Value provider. The value should be the Vault `path` of a K/V (v1) Secrets Engine (e.g., `nifi-kv`). Valid characters include alphanumeric, dash, and underscore.|_none_
|===
==== Optional properties
[options="header,footer"]
|===
|Property Name|Description|Default
|`vault.kv.version`|The Key/Value Secrets Engine version: `1` for unversioned, and `2` for versioned. This must match the versioned enabled in Vault.|`1`
|`vault.connection.timeout`|The connection timeout of the Vault client|`5 secs`
|`vault.read.timeout`|The read timeout of the Vault client|`15 secs`
|`vault.ssl.enabledCipherSuites`|A comma-separated list of the enabled TLS cipher suites|_none_
|`vault.ssl.enabledProtocols`|A comma-separated list of the enabled TLS protocols|_none_
|`vault.ssl.key-store`|Path to a keystore. Required if the Vault server is TLS-enabled|_none_
|`vault.ssl.key-store-type`|Keystore type (JKS, BCFKS or PKCS12). Required if the Vault server is TLS-enabled|_none_
|`vault.ssl.key-store-password`|Keystore password. Required if the Vault server is TLS-enabled|_none_
|`vault.ssl.trust-store`|Path to a truststore. Required if the Vault server is TLS-enabled|_none_
|`vault.ssl.trust-store-type`|Truststore type (JKS, BCFKS or PKCS12). Required if the Vault server is TLS-enabled|_none_
|`vault.ssl.trust-store-password`|Truststore password. Required if the Vault server is TLS-enabled|_none_
|===
[[aws-kms-provider]]
=== AWS KMS provider
This provider uses https://aws.amazon.com/kms/[AWS Key Management Service] for decryption. AWS KMS configuration properties can be stored in the `bootstrap-aws.conf` file, as referenced in `bootstrap.conf`. If the configuration properties are not specified in `bootstrap-aws.conf`, then the provider will attempt to use the AWS default credentials provider, which checks standard environment variables and system properties.
==== Required properties
[options="header,footer"]
|===
|Property Name|Description|Default
|`aws.kms.key.id`|The identifier or ARN that the AWS KMS client uses for encryption and decryption.|_none_
|===
==== Optional properties
===== All of the following must be configured, or will be ignored entirely.
[options="header,footer"]
|===
|Property Name|Description|Default
|`aws.region`|The AWS region used to configure the AWS KMS Client.|_none_
|`aws.access.key.id`|The access key ID credential used to access AWS KMS.|_none_
|`aws.secret.access.key`|The secret access key used to access AWS KMS.|_none_
|===
[[aws-secrets-manager-provider]]
=== AWS Secrets Manager provider
This provider uses https://aws.amazon.com/secrets-manager/[AWS Secrets Manager Service] to store and retrieve AWS Secrets. AWS Secrets Manager configuration properties can be stored in the `bootstrap-aws.conf` file, as referenced in `bootstrap.conf`. If the configuration properties are not specified in `bootstrap-aws.conf`, then the provider will attempt to use the AWS default credentials provider, which checks standard environment variables and system properties.
==== Optional properties
===== All of the following must be configured, or will be ignored entirely.
[options="header,footer"]
|===
|Property Name|Description|Default
|`aws.region`|The AWS region used to configure the AWS Secrets Manager Client.|_none_
|`aws.access.key.id`|The access key ID credential used to access AWS Secrets Manager.|_none_
|`aws.secret.access.key`|The secret access key used to access AWS Secrets Manager.|_none_
|===
[[azure-key-vault-key-provider]]
=== Azure Key Vault Key Provider
This protection scheme uses keys managed by
https://docs.microsoft.com/en-us/azure/key-vault/keys/about-keys[Azure Key Vault Keys] for encryption and decryption.
Azure Key Vault configuration properties can be stored in the `bootstrap-azure.conf` file, as referenced in the
`bootstrap.conf` of NiFi or NiFi Registry.
The provider will use the
https://docs.microsoft.com/en-us/java/api/com.azure.identity.defaultazurecredential[DefaultAzureCredential]
for authentication.
The https://docs.microsoft.com/en-us/java/api/overview/azure/identity-readme#key-concepts[Azure Identity] client library
describes the process for credentials resolution, which leverages environment variables, system properties, and falls
back to
https://docs.microsoft.com/en-us/java/api/overview/azure/identity-readme#managed-identity-support[Managed Identity]
authentication.
==== Required properties
[options="header,footer"]
|===
|Property Name|Description|Default
|`azure.keyvault.key.id`|The identifier of the key that the Azure Key Vault client uses for encryption and decryption.|_none_
|`azure.keyvault.encryption.algorithm`|The encryption algorithm that the Azure Key Vault client uses for encryption and decryption.|_none_
|===
[[azure-key-vault-secret-provider]]
=== Azure Key Vault Secret Provider
This protection scheme uses secrets managed by
https://docs.microsoft.com/en-us/azure/key-vault/secrets/about-secrets[Azure Key Vault Secrets] for storing and
retrieving protected properties.
Azure Key Vault configuration properties can be stored in the `bootstrap-azure.conf` file, as referenced in the
`bootstrap.conf` of NiFi or NiFi Registry.
The provider will use the
https://docs.microsoft.com/en-us/java/api/com.azure.identity.defaultazurecredential[DefaultAzureCredential]
for authentication.
The https://docs.microsoft.com/en-us/java/api/overview/azure/identity-readme#key-concepts[Azure Identity] client library
describes the process for credentials resolution, which leverages environment variables, system properties, and falls
back to
https://docs.microsoft.com/en-us/java/api/overview/azure/identity-readme#managed-identity-support[Managed Identity]
authentication.
Names of secrets stored in Azure Key Vault support alphanumeric and dash characters, but do not support characters such as `/` or `.`.
For this reason, NiFi replaces these characters with `-` when storing and retrieving secrets. The following table provides an example property name mapping:
[options="header,footer"]
|===
|Property Context|Property Name|Secret Name
|`default`|`nifi.security.keystorePasswd`|`default-nifi-security-keystorePasswd`
|===
==== Required properties
[options="header,footer"]
|===
|Property Name|Description|Default
|`azure.keyvault.uri`|URI for the Azure Key Vault service such as `https://{value-name}.vault.azure.net/` |_none_
|===
=== Google Cloud KMS provider
This protection scheme uses Google Cloud Key Management Service (https://cloud.google.com/security-key-management[Google Cloud Key Management Service]) for encryption and decryption. Google Cloud KMS configuration properties are to be stored in the `bootstrap-gcp.conf` file, as referenced in the `bootstrap.conf` of NiFi or NiFi Registry. Credentials must be configured as per the following documentation: https://cloud.google.com/kms/docs/reference/libraries[Google Cloud KMS documentation]
==== Required properties
[options="header,footer"]
|===
|Property Name|Description|Default
|`gcp.kms.project`|The project containing the key that the Google Cloud KMS client uses for encryption and decryption.|_none_
|`gcp.kms.location`|The geographic region of the project containing the key that the Google Cloud KMS client uses for encryption and decryption.|_none_
|`gcp.kms.keyring`|The keyring containing the key that the Google Cloud KMS client uses for encryption and decryption.|_none_
|`gcp.kms.key`|The key identifier that the Google Cloud KMS client uses for encryption and decryption.|_none_
|===
=== Property Context Mapping
Some encryption providers store protected values in an external service instead of persisting the encrypted values directly in the configuration file. To support this use case, a property context is defined for each protected property in NiFi's configuration files, in the format: `{context-name}/{property-name}`
* `context-name` - represents a namespace for properties in order to disambiguate properties with the same name. Without additional configuration, all protected properties are assigned the `default` context.
* `property-name` - contains the name of the property.
In order to support logical context names, mapping properties may be provided in `bootstrap.conf`, as follows:
```
nifi.bootstrap.protection.context.mapping.<context-name>=<identifier matching regex>
```
Here, `context-name` would determine the context name above, and `<identifier matching regex>` would map any property whose *group identifier* matched the provided Regular Expression. *Group identifiers* are defined per configuration file type, and are described as follows:
[options="header,footer"]
|===
|Configuration File|Group Identifier Description|Assigned Context
|`nifi.properties`|There is no concept of a group identifier here, since all property names should be unique.|_default_
|`authorizers.xml`|The `<identifier>` value of the XML block surrounding the property.|The mapped context name if RegEx matches the identifier, otherwise _default_
|`login-identity-providers.xml`|The `<identifier>` value of the XML block surrounding the property.|The mapped context name if RegEx matches the identifier, otherwise _default_
|===
==== Example
In the NiFi binary distribution, the `login-identity-providers.xml` file comes with a provider with the identifier `ldap-provider` and a property called `Manager Password`:
```
<provider>
<identifier>ldap-provider</identifier>
<class>org.apache.nifi.ldap.LdapProvider</class>
...
<property name="Manager Password"/>
...
</provider>
```
Similarly, the `authorizers.xml` file comes with a `ldap-user-group-provider` and a property also called `Manager Password`:
```
<userGroupProvider>
<identifier>ldap-user-group-provider</identifier>
<class>org.apache.nifi.ldap.tenants.LdapUserGroupProvider</class>
...
<property name="Manager Password"/>
...
</userGroupProvider>
```
If the Manager Password is desired to reference the same exact property (e.g., the same Secret in the HashiCorp Vault K/V provider) but still be distinguished from any other `Manager Password` property unrelated to LDAP, the following mapping could be added:
```
nifi.bootstrap.protection.context.mapping.ldap=ldap-.*
```
This would cause both of the above to be assigned a context of `"ldap/Manager Password"` instead of `"default/Manager Password"`.
[[admin-toolkit]]
== NiFi Toolkit Administrative Tools
The NiFi Toolkit also contains command line utilities for administrators to support NiFi maintenance in standalone and clustered environments.
@ -3012,7 +2797,6 @@ This cleanup mechanism takes into account only automatically created archived _f
|`nifi.authorizer.configuration.file`*|This is the location of the file that specifies how authorizers are defined. The default value is `./conf/authorizers.xml`.
|`nifi.login.identity.provider.configuration.file`*|This is the location of the file that specifies how username/password authentication is performed. This file is
only considered if `nifi.security.user.login.identity.provider` is configured with a provider identifier. The default value is `./conf/login-identity-providers.xml`.
|`nifi.ui.banner.text`|This is banner text that may be configured to display at the top of the User Interface. It is blank by default.
|`nifi.nar.library.directory`|The location of the nar library. The default value is `./lib` and probably should be left as is.
|`nifi.restore.directory`|The location that certain providers (e.g. UserGroupProviders) will look for previous configurations to restore from. There is no default value.
+
@ -3053,7 +2837,7 @@ The Database Settings section defines the settings for the internal database, wh
|====
|*Property*|*Description*
|`nifi.database.directory`*|The location of the H2 database directory. The default value is `./database_repository`.
|`nifi.database.directory`*|The location of the Flow Configuration History database directory. The default value is `./database_repository`.
|====
=== FlowFile Repository