Encrypting file contents in NiFi flows with PGP and age for data leaving your control
NiFi can encrypt and sign file contents inside the flow before the data leaves the platform, using EncryptContentPGP, SignContentPGP and EncryptContentAge. Teams usually need this when files leave NiFi for a partner's SFTP server, a cloud bucket or a long-term archive, and the data must stay protected after it lands outside your control. The processors protect the payload itself, so the file remains encrypted even if the transport is intercepted, the bucket is misconfigured or a copy is handled by someone outside the platform. EncryptContentPGP uses OpenPGP as described in RFC 4880, and EncryptContentAge uses the age-encryption.org/v1 format with ChaCha20-Poly1305 and X25519 keys, which is simpler to key but interoperates with fewer recipients' tools. Check with each recipient which format they can decrypt before you choose.
Encryption in the flow does not replace other controls. TLS still protects the connection to the partner or bucket, and it is what keeps credentials and metadata in transit private. Repository encryption and volume encryption protect FlowFiles, content and provenance while they sit on the NiFi nodes, and the sensitive properties key protects stored secrets, not your file payloads. Access control still decides who can open the flow, view the key material and change which recipient keys a processor uses. Confirm with your security team which of these layers they already rely on, and document how a recipient key is added, rotated and revoked, since a PGP or age key that is never retired is a long-lived exposure.
Before you build, decide who holds private keys, how public keys are imported into the key service, and how a failed encryption step routes files so that nothing unencrypted is sent on error. Plan a test with a sample file that the recipient decrypts independently, and confirm the processor properties and supported key formats against the current component documentation for your NiFi version, since the processor configuration is where most decryption failures originate. Also confirm whether your encrypted outputs must be signed, which is the job of SignContentPGP, and who verifies those signatures on the receiving side.
Which processor fits: OpenPGP, signing or age
This table compares the two OpenPGP processors, the age-based processor and the deprecated EncryptContent processor on the points that decide a choice: recipient ecosystem, key format, signing and partner interoperability. Read each row against what your receiving systems already accept, then confirm partner support before you build.
| Decision point | EncryptContentPGP | EncryptContentAge |
|---|---|---|
| Standard and format | OpenPGP as defined in RFC 4880, the format most file-exchange and partner tooling already reads | age-encryption.org/v1 specification, a newer and simpler format with ChaCha20-Poly1305 and X25519 keys |
| Key format | OpenPGP keys, managed through a key service in the flow | X25519 keys, managed through the processor's key configuration in the flow |
| Signing support | Encryption only in this processor. Pair with SignContentPGP to add an OpenPGP signature | Encryption only. Signing needs a separate control, so plan it in the flow design |
| Partner interoperability | Usually the default choice when the partner already runs GnuPG or another OpenPGP tool. Confirm the exact key types and cipher options they accept | Fits partners who run age tooling. Confirm they can read the age format before you commit, because many partner systems do not support it |
| Recipient ecosystem | Broad, established tooling across enterprises, banks and public agencies | Smaller ecosystem, typically used between teams or systems that agree on age explicitly |
| Deprecated EncryptContent | Replace EncryptContent with the PGP processors, which the component documentation positions as the successors for OpenPGP work | Replace EncryptContent with this processor where the data flow needs the age format |
| Migration effort from EncryptContent | Requires rebuilding the key handling and confirming the output format with each partner | Requires new keys and a format agreement with each recipient before cutover |
| What to confirm with partners | Accepted key algorithms, signature verification, compression and armor settings | Support for the age format, key exchange method and how they store private keys |
How to configure content encryption in a NiFi flow
This sequence takes content encryption from a design decision to a verified flow. Each step ends with a check you can record, so the encrypted output leaving NiFi can be opened only by the intended recipients and is shown to decrypt correctly before production traffic uses it.
Decide the recipient and key model
The data owner, the security lead and the recipient's team agree on who must be able to decrypt, whether each recipient has its own key pair, and whether the flow uses OpenPGP through EncryptContentPGP or age through EncryptContentAge. Record this in a short design note that lists recipients, key owners and the data classes covered. You know this step is done when every recipient has a named owner and the team can state which processor each destination requires.
Create or import recipient public keys
Each recipient generates its key pair on systems it controls and sends only the public key to the team building the flow. Private keys never enter NiFi, so the flow needs public material for encryption. Confirm each key's fingerprint with the recipient through a channel other than the one that delivered the key, then store the approved keys in a location with restricted access. The step closes when the fingerprint list matches what the recipients reported.
Configure the key service controller services
On the NiFi canvas, add the key service controller service that matches your chosen format, point it at the approved public keys, and enable it. Limit who can view and modify the service, because key locations and key material are sensitive configuration. Check that the service is enabled, reports that it can read each expected key, and shows no validation errors in the bulletin board. If a key is missing or unreadable, fix the path or file permissions before any processor references the service.
Place the encryption processor after content is final
Add EncryptContentPGP or EncryptContentAge after every step that changes content, such as parsing, enrichment, filtering and format conversion, and directly before the processor that sends data out. Set it to use the key service you configured. If an existing flow still uses the older EncryptContent processor, confirm the replacement in the component documentation before you retire it. Trace each path to the egress processor and confirm that every path passes through encryption and that no path reaches the destination unencrypted.
Sign content when origin must be proven
Where the receiver needs to confirm who produced the data, add SignContentPGP with a signing key that your team controls. Place it according to the component documentation so the signature covers the content the recipient decrypts, and keep the signing key in its own key service with restricted access. Do not reuse recipient keys for signing. Check that the receiver's tooling validates the signature on a test file. If signing is not required, record that decision in the design note and skip this step.
Route failures away from the egress path
Connect the failure and error relationships of each encryption processor to a quarantine or retry path that never reaches the destination. Do not auto-terminate these relationships, because a failed encryption must stay visible to operators. Attach a bulletin or alert to the failure path. In a non-production environment, point a test file at a deliberately disabled or unreadable key and confirm that the file stops on the failure path and nothing arrives at the destination.
Verify with a round-trip test file
Create a known test file, run it through the complete flow in a non-production environment, and retrieve the encrypted output from the destination. Decrypt it with the recipient's tooling outside NiFi, using the recipient's private key, and compare the hash of the result with the hash of the original file. The step is done when the hashes match, the stored file contains no readable plaintext, and provenance shows the encryption processor handled the file. Repeat this test after any key change.
How key services and sensitive values fit together
Public keys and private keys live in different places, and only the private side needs protection from the people who run the flow. The PGP and age processors reference key material through their configuration, and the processors are the consumers of that material, not its owners. For PGP, the encryption side needs recipient public keys, while decryption and signing need private keys and their passphrases. For age, encryption uses X25519 recipient public keys, and decryption needs the matching private identity. Before building anything, map each key to the flow that uses it, the people allowed to change that flow, and the system that stores the key outside NiFi. Confirm in the component documentation for EncryptContentPGP and EncryptContentAge which properties accept a key directly and which expect a key service or a file path, because that choice decides where the secret ends up.
Where a private key or passphrase is entered as a property value, NiFi stores it in the flow definition in encrypted form, protected by the nifi.sensitive.props.key value in nifi.properties. That protection is only as good as the key itself, and the same key must match across every cluster node. Confirm with the NiFi administration guide what the sensitive properties key covers, and whether exported flow definitions or parameter values carry the protected value or a placeholder. Parameters add a second path: if a private key is held in a parameter that is marked sensitive, it is protected like other sensitive parameter values, but anyone who can read the parameter context in the UI or through the API may still be able to see non-sensitive parameters that reference key locations. Keep private material in sensitive parameters or an external secret store, keep public keys in ordinary parameters where they can be reviewed, and test what a read-only user can see in the UI before go-live.
Security and operational risks to plan for
Encrypting content inside a flow moves the security question from the transport layer to the keys, the logs and the failure paths. The cards below cover the places where PGP and age encryption most often fail in production, and each one names a control your team can check before go-live.
Key custody and storage
Private keys and passphrases decide whether encrypted files can ever be opened, so they must never sit in a flow definition or a plain parameter. Store private keys in the key service, keep passphrases in sensitive parameters, and confirm that the flow export does not carry key material. Verify by exporting a flow and searching the output for key markers and passphrase values before any sign-off.
Key rotation and archive decryption
Rotating a key does not re-encrypt files already written, so every archived file still depends on the key that sealed it. Record which key ID or recipient set was used for each output, keep retired private keys under the same custody rules for the full retention period, and test a decrypt of an old file after each rotation. Ask the team who owns that retention decision.
Logs and provenance without plaintext
Bulletins, debug logs and provenance events can expose content or key details if teams enable verbose logging on encryption processors. Review the log levels for the processor's logger, check what attributes are written to provenance, and confirm that FlowFile attributes holding key identifiers or passphrases are marked sensitive. Test by triggering an encryption error and reading the bulletin and log output.
Restricted access to key services
Anyone who can change a key service or the flow that references it can redirect output to a key they control. Limit modify rights on the process group that holds the encryption flow, and restrict view rights on the controller services that hold key material. Check the authorization policies for those components against a named list of approved operators.
Failure routing that blocks plaintext
When encryption fails, a flow that routes the original FlowFile to a success path or to an unmonitored relationship can send unencrypted content downstream. Route the failure relationship to a dead-end queue or an alerting path, and make sure no connection from the encryption processor's failure relationship reaches a delivery processor. Verify with a flow test that forces a bad recipient key and confirms nothing is delivered.
Replacing EncryptContent in existing NiFi 2 flows
Start by building a complete inventory of every flow that still uses the deprecated EncryptContent processor, including flows in process groups you rarely open, flows that are stopped, and templates or parameter-driven copies that teams may have forked. For each instance, record the processor's configured mode (encrypt or decrypt), the algorithm and key material it uses, the upstream and downstream components, and the systems that consume the output. Export the flow definitions from your version-controlled registry or from the running canvas so the inventory reflects what is deployed, not what someone remembers. Then map each use to its successor. Encryption to OpenPGP recipients generally maps to EncryptContentPGP, and encryption that the consumer can open with an age identity maps to EncryptContentAge. Confirm the current property names, supported options and decryption counterparts in the EncryptContentPGP component documentation and the EncryptContentAge component documentation before you change anything, because a replacement is not a drop-in swap of property values.
Testing matters more than the mapping itself. Run the replacement against copies of representative FlowFiles and confirm that the receiving system decrypts the output, verifies any signature, and parses the plaintext exactly as it did before. Check the file naming, extensions, armor or binary format and any metadata attributes that downstream steps rely on. Keep the old and new paths running side by side in a non-production environment for long enough to cover your normal batch and retry cycles, and record any consumer that fails. Plan cutover per flow, not per platform, so that a problem with one partner feed does not block the rest. Keep the key material and recipient lists under the same change control as the flow itself, and retain the previous flow version so you can roll back.
Plan the review of flows and custom code as part of the 2.x upgrade path, not as an afterthought. Custom processors, scripts and controller services that call the old processor or depend on its attributes may need changes, and the NiFi Migration Guidance describes the upgrade steps that affect existing flows. Ask your team to confirm the behavior of each replacement against the current component documentation for the NiFi release you are deploying, since processor behavior and property sets can change between releases. Record the results of each test and cutover decision so that auditors and your own change board can trace which flows moved, when they moved, and which consumers were verified.
Limits to confirm in your environment
The PGP and age processors look similar in a flow, but they differ in key formats, interoperability and failure behavior. The cards below list the limits to verify against the current NiFi component documentation and your own partners before you commit a design to production.
Supported key formats and sizes
Confirm which key types, algorithms and key sizes each processor accepts for your scenario. EncryptContentAge uses X25519 keys and the age-encryption.org/v1 format, while EncryptContentPGP follows OpenPGP. Check whether your key generation tooling produces keys in a form the processor reads, and whether passphrase-protected private keys are supported in your flow version.
Partner compatibility with age and OpenPGP
Before you rely on either format, test a round trip with the software your recipient actually runs. Interoperability depends on the cipher, the packet structure and the version of the decryption tool on the far side. Ask each partner which tool and version they use, and keep a small set of test files that both sides have decrypted successfully.
Performance on large files
Encryption adds CPU work and holds content in memory or on the content repository while it runs. Measure throughput with files at the sizes you expect in production, not with small samples. Watch heap use, queue back pressure and the effect on other processors in the same process group before you set concurrency or file size limits.
Behavior across cluster nodes
Every node that runs the encryption processor needs access to the same public keys, and private keys used for signing must be available where those processors run. Confirm how key services and key files are distributed on each node, how a node with a missing or mismatched key fails, and whether failed FlowFiles route cleanly to a failure relationship for retry.
Signature verification on the receiving side
Encryption protects confidentiality but does not prove who sent the file. Decide whether the recipient must verify a signature from SignContentPGP, and if so, agree on the signing key, its fingerprint and how the verification step is performed. Record that decision in the design, because a flow that encrypts without signing cannot show origin to an auditor.
Migration from EncryptContent
Flows that still use the deprecated EncryptContent processor need an inventory of their algorithms, key handling and output formats before replacement. Confirm that the new processors can read output the old flows produced, and plan a parallel run that compares decrypted results before you retire the old path. Confirm the exact migration path against the NiFi 2 component documentation for your release.
Questions teams ask before encrypting NiFi content
What drives the effort of encrypting content in NiFi flows?
The main drivers are how many flows touch encrypted data, how many keys and recipients the design needs, and whether existing flows use the deprecated EncryptContent processor. Each flow needs its encryption step, its decryption step on the receiving side, and tests that prove the output can be read by the intended recipients. A single PGP recipient for one feed is a small job. Dozens of flows with several partners, separate keys per partner and a migration off EncryptContent is a much larger one. Ask for the effort breakdown per flow and per partner in any written scope, so you can see what each change covers.
What does the work need from our team?
Three roles matter most. Key custodians decide who generates, holds and rotates the private keys and passphrases, and they must agree on where those secrets are stored. Flow owners confirm the data formats, file naming, retry behavior and what the downstream system expects. Partner contacts provide public keys or age recipients, and confirm how they will decrypt and verify signatures. Each partner also needs a test path, such as a non-production endpoint or a sample file exchange, before anything moves to production. Missing any of these roles is the most common reason testing stalls.
Can our own team encrypt flows without a partner?
Yes, if your team already runs NiFi in production and has someone comfortable with key management. The processors are part of Apache NiFi, which is released under the Apache License 2.0, so there is no license fee for the components themselves. The harder parts are operational: generating keys correctly, storing private keys outside the flow, testing decryption with each recipient, and handling key rotation. Teams that build this in-house usually still need a reviewer who has checked the key handling and the test evidence. A partner can take on any of these steps within a written scope.
How long does partner testing take?
Testing length depends mostly on partner readiness, not on the NiFi work itself. A partner that can receive test files, return decrypted results and confirm signature checks within a few exchanges moves quickly. A partner that needs to install tooling, approve a key exchange through its own process or change its receiving system will extend the schedule. No testing duration is fixed in this page, so ask for the test plan, the number of exchange rounds it assumes and the partner tasks each round depends on. Those inputs set the timeline in any written scope.
Should we choose PGP or age for a new flow?
Choose based on what the receiving party already runs. EncryptContentPGP uses OpenPGP as described in RFC 4880, which suits partners with existing GnuPG or PGP tooling and signature workflows. EncryptContentAge uses the age-encryption.org/v1 specification with ChaCha20-Poly1305 and X25519 keys, which is simpler to set up when both sides control their tooling. If a partner already relies on OpenPGP keys, age adds a second format to support. Confirm the recipient's supported formats before you design the flow, because changing the format later means changing both ends.
What happens to existing EncryptContent flows?
Flows built on the EncryptContent processor need to be inventoried and moved to the processors that replace it. Each replacement changes configuration, property names and sometimes the output format, so downstream partners may need to decrypt output differently after the change. Plan a parallel run where old and new outputs are compared, and keep the old flow available until the partner confirms successful decryption. Count the number of flows and partners affected before estimating the migration, because that count drives most of the work.
How do we keep private keys and sensitive values out of the flow?
Store private keys and passphrases in a secrets system or a key service your organization already controls, and reference them through controller services rather than typing them into processor properties. Keep public keys and age recipients in configuration that reviewers can read. Confirm how the sensitive properties key protects values stored in the NiFi configuration, and plan rotation for both the encryption keys and that NiFi key. Ask any partner to show where each secret lives and who can read it, and to include that check in the test evidence.
Does encryption in a flow satisfy our transfer and audit requirements?
Encryption in a flow protects content before it leaves NiFi, but it does not by itself meet every transfer, logging or change management requirement. Auditors usually ask who can read keys, how keys are rotated, how changes to the flow are approved and what evidence shows that files were encrypted and decrypted correctly. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue any audit report or certification. Confirm the specific requirements with your assessor before scoping the work.
How DeployOpen scopes NiFi content encryption work
DeployOpen scopes content encryption in writing before any flow is changed. The scope names each flow that will encrypt or sign content, the direction of travel (which processors run before data leaves NiFi and which systems receive it), the recipients and their key types, and the processors being replaced. For flows still using the deprecated EncryptContent processor, the scope also records which replacement applies: EncryptContentPGP and SignContentPGP for OpenPGP recipients, or EncryptContentAge where the receiving side supports age and X25519 keys. Where a partner receives files, the scope records who holds the private keys and how a recipient's key is exchanged and verified, because that exchange decides whether the encryption protects anything.
DeployOpen implements the work inside your own NiFi environment, whether that is your cluster, your Kubernetes namespace or an air-gapped network. Key material stays under your control. Keys and key service configuration are handled with your sensitive properties and secrets practices, and the build includes test flows that encrypt, sign and decrypt sample files so both sides of each exchange are checked. Documentation covers the processor settings, the key inventory, the rotation steps and the owners for each key. Ask any partner to show where private keys are generated, where they are stored and who can read them in NiFi, including through provenance and exported flow definitions.
DeployOpen prepares the systems, controls and evidence that independent auditors and certification bodies need to assess encryption and key handling. It does not issue audit reports, attestations or certifications, and the scope should say so. Ongoing key rotation, processor upgrades for NiFi 2 and periodic verification of encrypted exchanges can be covered by a support retainer, and that retainer is agreed in writing with its own scope. Quotes follow from the written scope, so ask for the flows, key counts and recipients in scope, what is one-time and what recurs, and who performs each verification step.
