You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nifi.apache.org by th...@apache.org on 2021/08/27 16:31:50 UTC
[nifi] branch main updated: NIFI-9016 Added BCFKS
KeyStoreKeyProvider examples to User Guide
This is an automated email from the ASF dual-hosted git repository.
thenatog pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/nifi.git
The following commit(s) were added to refs/heads/main by this push:
new ed4d4d5 NIFI-9016 Added BCFKS KeyStoreKeyProvider examples to User Guide
ed4d4d5 is described below
commit ed4d4d59388ebedd9df17c9c457130b8764e4624
Author: exceptionfactory <ex...@apache.org>
AuthorDate: Thu Aug 5 17:00:28 2021 -0500
NIFI-9016 Added BCFKS KeyStoreKeyProvider examples to User Guide
Signed-off-by: Nathan Gough <th...@gmail.com>
This closes #5285.
---
nifi-docs/src/main/asciidoc/user-guide.adoc | 115 +++++++++++++---------------
1 file changed, 52 insertions(+), 63 deletions(-)
diff --git a/nifi-docs/src/main/asciidoc/user-guide.adoc b/nifi-docs/src/main/asciidoc/user-guide.adoc
index e7b398b..6c9b2bb 100644
--- a/nifi-docs/src/main/asciidoc/user-guide.adoc
+++ b/nifi-docs/src/main/asciidoc/user-guide.adoc
@@ -2935,32 +2935,19 @@ key5=c6FzfnKm7UR7xqI2NFpZ+fEKBfSU7+1NvRw+XWQ9U39MONWqk5gvoyOCdFR1kUgeg46jrN5dGXk
Each line defines a key ID and then the Base64-encoded cipher text of a 16 byte IV and wrapped AES-128, AES-192, or AES-256 key depending on the JCE policies available. The individual keys are wrapped by AES/GCM encryption using the **root key** defined by `nifi.bootstrap.sensitive.key` in _conf/bootstrap.conf_.
===== KeyStoreKeyProvider
-The `KeyStoreKeyProvider` implementation reads from a standard `java.security.KeyStore` using the configured password to load AES Secret Key entries.
-The provider supports the following Keystore Types:
+See <<secret-key-generation-and-storage-using-keytool>> for details on generating and storing an AES Secret Key for use with the `KeyStoreKeyProvider`.
-* BCFKS
-* PKCS12
-
-The keystore filename extension must be either `.p12` indicating PKCS12 or `.bcfks` indicating BCFKS.
-
-The `keytool` command can be used to generate an AES-256 Secret Key stored in a PKCS12 file for repository encryption:
-
-...
-keytool -genseckey -alias primary-key -keyalg AES -keysize 256 -keystore repository.p12 -storetype PKCS12
-...
+The following configuration properties support using a PKCS12 keystore with a Secret Key:
-Enter a keystore password when prompted. The same value must be used for both the keystore password and key password.
-The keystore password will be used in the provider configuration properties.
+ nifi.provenance.repository.encryption.key.provider.implementation=org.apache.nifi.security.kms.KeyStoreKeyProvider
+ nifi.provenance.repository.encryption.key.provider.location=./conf/repository.p12
+ nifi.provenance.repository.encryption.key.provider.password=KEYSTORE_PASSWORD
+ nifi.provenance.repository.encryption.key.id=primary-key
-The following configuration properties support using a PKCS12 keystore with a Secret Key:
+The same configuration can be used with a BCFKS keystore using a different location property:
-...
-nifi.provenance.repository.encryption.key.provider.implementation=org.apache.nifi.security.kms.KeyStoreKeyProvider
-nifi.provenance.repository.encryption.key.provider.location=./conf/repository.p12
-nifi.provenance.repository.encryption.key.provider.password=KEYSTORE_PASSWORD
-nifi.provenance.repository.encryption.key.id=primary-key
-...
+ nifi.provenance.repository.encryption.key.provider.location=./conf/repository.bcfks
[[provenance-repository-key-rotation]]
===== Key Rotation
@@ -3042,32 +3029,19 @@ key5=c6FzfnKm7UR7xqI2NFpZ+fEKBfSU7+1NvRw+XWQ9U39MONWqk5gvoyOCdFR1kUgeg46jrN5dGXk
Each line defines a key ID and then the Base64-encoded cipher text of a 16 byte IV and wrapped AES-128, AES-192, or AES-256 key depending on the JCE policies available. The individual keys are wrapped by AES/GCM encryption using the **root key** defined by `nifi.bootstrap.sensitive.key` in _conf/bootstrap.conf_.
==== KeyStoreKeyProvider
-The `KeyStoreKeyProvider` implementation reads from a standard `java.security.KeyStore` using the configured password to load AES Secret Key entries.
-The provider supports the following Keystore Types:
+See <<secret-key-generation-and-storage-using-keytool>> for details on generating and storing an AES Secret Key for use with the `KeyStoreKeyProvider`.
-* BCFKS
-* PKCS12
-
-The keystore filename extension must be either `.p12` indicating PKCS12 or `.bcfks` indicating BCFKS.
-
-The `keytool` command can be used to generate an AES-256 Secret Key stored in a PKCS12 file for repository encryption:
-
-...
-keytool -genseckey -alias primary-key -keyalg AES -keysize 256 -keystore repository.p12 -storetype PKCS12
-...
+The following configuration properties support using a PKCS12 keystore with a Secret Key:
-Enter a keystore password when prompted. The same value must be used for both the keystore password and key password.
-The keystore password will be used in the provider configuration properties.
+ nifi.content.repository.encryption.key.provider.implementation=org.apache.nifi.security.kms.KeyStoreKeyProvider
+ nifi.content.repository.encryption.key.provider.location=./conf/repository.p12
+ nifi.content.repository.encryption.key.provider.password=KEYSTORE_PASSWORD
+ nifi.content.repository.encryption.key.id=primary-key
-The following configuration properties support using a PKCS12 keystore with a Secret Key:
+The same configuration can be used with a BCFKS keystore using a different location property:
-...
-nifi.content.repository.encryption.key.provider.implementation=org.apache.nifi.security.kms.KeyStoreKeyProvider
-nifi.content.repository.encryption.key.provider.location=./conf/repository.p12
-nifi.content.repository.encryption.key.provider.password=KEYSTORE_PASSWORD
-nifi.content.repository.encryption.key.id=primary-key
-...
+ nifi.content.repository.encryption.key.provider.location=./conf/repository.bcfks
.Data Protection vs. Key Protection
****
@@ -3156,32 +3130,19 @@ key5=c6FzfnKm7UR7xqI2NFpZ+fEKBfSU7+1NvRw+XWQ9U39MONWqk5gvoyOCdFR1kUgeg46jrN5dGXk
Each line defines a key ID and then the Base64-encoded cipher text of a 16 byte IV and wrapped AES-128, AES-192, or AES-256 key depending on the JCE policies available. The individual keys are wrapped by AES/GCM encryption using the **root key** defined by `nifi.bootstrap.sensitive.key` in _conf/bootstrap.conf_.
==== KeyStoreKeyProvider
-The `KeyStoreKeyProvider` implementation reads from a standard `java.security.KeyStore` using the configured password to load AES Secret Key entries.
-
-The provider supports the following Keystore Types:
-
-* BCFKS
-* PKCS12
-The keystore filename extension must be either `.p12` indicating PKCS12 or `.bcfks` indicating BCFKS.
+See <<secret-key-generation-and-storage-using-keytool>> for details on generating and storing an AES Secret Key for use with the `KeyStoreKeyProvider`.
-The `keytool` command can be used to generate an AES-256 Secret Key stored in a PKCS12 file for repository encryption:
+The following configuration properties support using a PKCS12 keystore with a Secret Key:
-...
-keytool -genseckey -alias primary-key -keyalg AES -keysize 256 -keystore repository.p12 -storetype PKCS12
-...
+ nifi.flowfile.repository.encryption.key.provider.implementation=org.apache.nifi.security.kms.KeyStoreKeyProvider
+ nifi.flowfile.repository.encryption.key.provider.location=./conf/repository.p12
+ nifi.flowfile.repository.encryption.key.provider.password=KEYSTORE_PASSWORD
+ nifi.flowfile.repository.encryption.key.id=primary-key
-Enter a keystore password when prompted. The same value must be used for both the keystore password and key password.
-The keystore password will be used in the provider configuration properties.
+The same configuration can be used with a BCFKS keystore using a different location property:
-The following configuration properties support using a PKCS12 keystore with a Secret Key:
-
-...
-nifi.flowfile.repository.encryption.key.provider.implementation=org.apache.nifi.security.kms.KeyStoreKeyProvider
-nifi.flowfile.repository.encryption.key.provider.location=./conf/repository.p12
-nifi.flowfile.repository.encryption.key.provider.password=KEYSTORE_PASSWORD
-nifi.flowfile.repository.encryption.key.id=primary-key
-...
+ nifi.flowfile.repository.encryption.key.provider.location=./conf/repository.bcfks
[[flowfile-repository-key-rotation]]
==== Key Rotation
@@ -3198,6 +3159,34 @@ During swaps and recoveries, the flowfile records are deserialized and reseriali
Within the NiFi UI/API, there is no detectable difference between an encrypted and unencrypted flowfile repository. All framework interactions with flowfiles work as expected with no change to the process.
+[[secret-key-generation-and-storage-using-keytool]]
+=== Secret Key Generation and Storage using Keytool
+
+The `KeyStoreKeyProvider` supports reading from a `java.security.KeyStore` using a configured password to load AES Secret Key entries.
+The `KeyStoreKeyProvider` can be configured with any of the encrypted repository implementations.
+
+The provider supports the following KeyStore Types:
+
+* BCFKS
+* PKCS12
+
+The keystore filename extension must be either `.p12` indicating PKCS12 or `.bcfks` indicating BCFKS.
+
+The `keytool` command can be used to generate an AES-256 Secret Key stored in a PKCS12 file for repository encryption:
+
+ keytool -genseckey -alias primary-key -keyalg AES -keysize 256 -keystore repository.p12 -storetype PKCS12
+
+The `keytool` command requires additional arguments specifying the BouncyCastle Security Provider to store
+Secret Keys using BCFKS. The arguments must include a reference to the BouncyCastle Security Provider library, which
+is available in the `lib/bootstrap` directory under the NiFi installation.
+
+The following command can be used to generate an AES-256 Secret Key stored using BCFKS:
+
+ keytool -genseckey -alias primary-key -keyalg AES -keysize 256 -keystore repository.bcfks -storetype BCFKS -providerclass org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath lib/bootstrap/bcprov-jdk15on-*.jar
+
+Enter a keystore password when prompted. The same value must be used for both the keystore password and key password.
+The keystore password will be used in the provider configuration properties.
+
=== Potential Issues
[WARNING]