David Handermann created NIP-43:
-----------------------------------
Summary: Support Pluggable Property Encryption Providers
Key: NIP-43
URL: https://issues.apache.org/jira/browse/NIP-43
Project: NiFi Improvement Proposal
Issue Type: New Feature
Reporter: David Handermann
Assignee: David Handermann
h2. Motivation
Apache NiFi protects sensitive property values, including component properties,
Parameter values, and stored authorization tokens, using a single encryption
implementation built into the framework. The Keyed Cipher Property Encryptor
derives an AES-GCM key from the sensitive properties key configured in
nifi.properties, using Argon2id or PBKDF2 as the key derivation function.
This design constrains deployments in several ways. The key material resides in
nifi.properties on the same host as the flow configuration it protects, so the
secret and the encrypted values share a single trust boundary. Organizations
that require key custody in a Key Management System or Hardware Security Module
have no supported path. Rotating the key requires stopping the application and
re-encrypting the flow configuration.
The existing Property Encryptor interface accepts only a value, with no
indication of what that value represents. Encrypted values carry no binding to
the component or Parameter that owns them, so a value copied from one location
in a flow to another decrypts successfully in its new location. External key
management services expect an encryption context for authenticated additional
data and audit attribution, which the current interface cannot supply.
h2. Scope
The scope includes a new framework extension point located in the NiFi
Framework API, a default implementation that preserves current behavior, and
configuration in the Flow Controller to select and initialize the configured
implementation.
Supplying encryption context requires threading a context argument through
framework interfaces that currently pass values alone, including the Sensitive
Value Encryptor and Property Decryptor interfaces in the framework core API,
along with the Parameter Value Mapper and the flow mapping and synchronization
classes that call them. These changes do not require any modifications or
additions to the public Apache NiFi API.
The existing Property Encryptor interface remains unchanged. The bootstrap
process and the flow encryptor command run outside the extension framework and
cannot load implementations from a NAR, so they continue to use the current
implementation directly.
h2. Description
The proposed extension point defines a Property Encryption Provider with an
identifier, a lifecycle, and symmetric operations that accept the value
together with the context describing it.
{code:java}
public interface PropertyEncryptionProvider extends Closeable {
String getIdentifier();
void initialize(PropertyEncryptionProviderInitializationContext context);
byte[] encrypt(byte[] property, SensitivePropertyContext context);
byte[] decrypt(byte[] encryptedProperty, SensitivePropertyContext context);
@Override
default void close() throws IOException {
}
}
{code}
A single Sensitive Property Context argument on both operations covers
component properties, Parameters, and stored authorization tokens without
separate overloads for each case. The context provides a category indicating
the kind of value being protected, together with attributes such as the
component identifier, property name, Parameter Context name, and Parameter name.
Implementations backed by a Key Management System can supply these attributes
as encryption context and rely on the service to record them for auditing.
Implementations must be thread safe, because the framework holds a single
shared instance. Failures are reported through a dedicated unchecked exception,
and the initialization context supplies configured properties along with a TLS
configuration for implementations that call remote services.
Loading follows the pattern already established for the Asset Manager and other
framework extensions. An implementation class property and a properties prefix
in nifi.properties select and configure the implementation, which the framework
instantiates through the NAR Thread Context Class Loader and invokes using the
class loader of its own NAR.
The default implementation ships with the framework and wraps the current Keyed
Cipher Property Encryptor, so an installation with no additional configuration
behaves as it does today. Values are encoded with the identifier of the
provider that wrote them, so the framework can select the correct
implementation when reading, and values without an identifier are routed to the
default implementation.
h2. Compatibility
Initial implementation will add the extension point, register the default
implementation, and connect the framework to the configured provider. Existing
deployments are unaffected on upgrade. Values encrypted by earlier versions
continue to decrypt, and installations that configure no provider continue to
use the built-in implementation with the existing sensitive properties key.
Values written by an alternate provider can be read only by a deployment with
the same provider installed and configured, so moving a flow configuration
between environments requires the same provider in both. The Headless NiFi
Server and the Stateless engine construct encryptors independently of the
standard server configuration and are not affected.
h2. Verification
Unit tests will cover encoding and selection of provider implementations,
propagation of context attributes from flow mapping and Parameter handling, and
behavior of the default implementation against values produced by the current
implementation. System tests will verify a complete flow round trip, including
component property and Parameter encryption, using a provider other than the
default. Existing sensitive property tests will be retained against the default
implementation.
h2. Alternatives
Replacing existing key derivation functions would address some trust boundary
concerns, but require direct implementation within the project. This is a
smaller change, but it leaves key material on the local file system and
provides no path to external key custody, encryption context, or centralized
auditing.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
