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

NIFI-7341 Updated certificate commands and source code formatting in Toolkit Guide. (#4196)

This commit is contained in:
Andy LoPresto 2020-04-09 10:13:53 -07:00 committed by GitHub
parent 84968e70d2
commit 1ec7e31f11
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
nifi-docs/src/main/asciidoc/toolkit-guide.adoc
View File

@ -130,7 +130,8 @@ In order to avoid specifying the URL (and possibly other optional arguments for
An example properties file for a local NiFi Registry instance would look like the following:
```
[source]
----
baseUrl=http://localhost:18080
keystore=
keystoreType=
@ -140,7 +141,7 @@ An example properties file for a local NiFi Registry instance would look like th
truststoreType=
truststorePasswd=
proxiedEntity=
```
----
This properties file can then be used on a command by specifying `-p`:
@ -184,7 +185,8 @@ The examples below are for NiFi Registry, but the same concept applies for NiFi
==== Example - Secure NiFi Registry without Proxied-Entity
Assuming we have a keystore containing the certificate for "CN=user1, OU=NIFI", an example properties file would be the following:
```
[source]
----
baseUrl=https://localhost:18443
keystore=/path/to/keystore.jks
keystoreType=JKS
@ -193,14 +195,15 @@ Assuming we have a keystore containing the certificate for "CN=user1, OU=NIFI",
truststore=/path/to/truststore.jks
truststoreType=JKS
truststorePasswd=changeme
```
----
In this example, commands will be executed as "CN=user1, OU=NIFI". This user would need to be a user in NiFi Registry, and commands accessing buckets would be restricted to buckets this user has access to.
==== Example - Secure NiFi Registry with Proxied-Entity
Assuming we have access to the keystore of NiFi Registry itself, and that NiFi Registry is also configured to allow Kerberos or LDAP authentication, an example properties file would be the following:
```
[source]
----
baseUrl=https://localhost:18443
keystore=/path/to/keystore.jks
keystoreType=JKS
@ -210,7 +213,7 @@ Assuming we have access to the keystore of NiFi Registry itself, and that NiFi R
truststoreType=JKS
truststorePasswd=changeme
proxiedEntity=user1@NIFI.COM
```
----
In this example, the certificate in _keystore.jks_ would be for the NiFi Registry server, for example "CN=localhost, OU=NIFI". This identity would need to be defined as a user in NiFi Registry and given permissions to 'Proxy'.
@ -319,7 +322,8 @@ The reason step 4 was able to reference the results from step 2, is because the
=== Adding Commands
To add a NiFi command, create a new class that extends `AbstractNiFiCommand`:
```
[source]
----
public class MyCommand extends AbstractNiFiCommand {
public MyCommand() {
@ -337,13 +341,14 @@ public class MyCommand extends AbstractNiFiCommand {
return "This is my new command";
}
}
```
----
Add the new command to `NiFiCommandGroup`:
```
[source]
----
commands.add(new MyCommand());
```
----
To add a NiFi Registry command, perform the same steps, but extend from `AbstractNiFiRegistryCommand`, and add the command to `NiFiRegistryCommandGroup`.
@ -384,7 +389,8 @@ The following are available options:
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:
```
[source]
----
# security properties #
nifi.sensitive.props.key=thisIsABadSensitiveKeyPassword
nifi.sensitive.props.algorithm=PBEWITHMD5AND256BITAES-CBC-OPENSSL
@ -398,7 +404,7 @@ nifi.security.keyPasswd=thisIsABadKeyPassword
nifi.security.truststore=
nifi.security.truststoreType=
nifi.security.truststorePasswd=
```
----
Enter the following arguments when using the tool:
@ -411,7 +417,8 @@ encrypt-config.sh
As a result, the _nifi.properties_ file is overwritten with protected properties and sibling encryption identifiers (`aes/gcm/256`, the currently supported algorithm):
```
[source]
----
# security properties #
nifi.sensitive.props.key=n2z+tTTbHuZ4V4V2||uWhdasyDXD4ZG2lMAes/vqh6u4vaz4xgL4aEbF4Y/dXevqk3ulRcOwf1vc4RDQ==
nifi.sensitive.props.key.protected=aes/gcm/256
@ -428,14 +435,15 @@ nifi.security.keyPasswd.protected=aes/gcm/256
nifi.security.truststore=
nifi.security.truststoreType=
nifi.security.truststorePasswd=
```
----
Additionally, the _bootstrap.conf_ file is updated with the encryption key as follows:
```
[source]
----
# Master key in hexadecimal format for encrypted sensitive configuration values
nifi.bootstrap.sensitive.key=0123456789ABCDEFFEDCBA98765432100123456789ABCDEFFEDCBA9876543210
```
----
Sensitive configuration values are encrypted by the tool by default, however you can encrypt any additional properties, if desired. To encrypt additional properties, specify them as comma-separated values in the `nifi.sensitive.props.additional.keys` property.
@ -445,7 +453,8 @@ When applied to _login-identity-providers.xml_ and _authorizers.xml_, the proper
Example of protected _login-identity-providers.xml_:
```
[source]
----
<!-- LDAP Provider -->
<provider>
<identifier>ldap-provider</identifier>
@ -458,11 +467,12 @@ Example of protected _login-identity-providers.xml_:
<property name="TLS - Keystore Type"></property>
...
</provider>
```
----
Example of protected _authorizers.xml_:
```
[source]
----
<!-- LDAP User Group Provider -->
<userGroupProvider>
<identifier>ldap-user-group-provider</identifier>
@ -475,7 +485,7 @@ Example of protected _authorizers.xml_:
<property name="TLS - Keystore Type"></property>
...
</userGroupProvider>
```
----
== File Manager
The File Manager utility (invoked as `./bin/file-manager.sh` or `bin\file-manager.bat`) allows system administrators to take a backup of an existing NiFi installation, install a new version of NiFi in a designated location (while migrating any previous configuration settings) or restore an installation from a previous backup. File Manager supports NiFi version 1.0.0 and higher.
@ -873,7 +883,8 @@ In some enterprise scenarios, a security/IT team may provide a signing certifica
* If the `-o` argument is not provided, the default working directory (`.`) must contain `nifi-cert.pem` and `nifi-key.key`
** e.g. `$ cd ./hardcoded/ && ../toolkit/bin/tls-toolkit.sh standalone -n 'node5.nifi.apache.org' -P thisIsABadPassword -S thisIsABadPassword -O`
```
[source]
----
# Example directory structure *before* commands above are run
🔓 0s @ 18:07:58 $ tree -L 2
@ -894,13 +905,14 @@ In some enterprise scenarios, a security/IT team may provide a signing certifica
   ├── conf
   ├── docs
   └── lib
```
----
The `nifi-cert.pem` and `nifi-key.key` files should be ASCII-armored (Base64-encoded ASCII) files containing the CA public certificate and private key respectively. Here are sample files of each to show the expected format:
==== nifi-cert.pem
```
[source]
----
# The first command shows the actual content of the encoded file, and the second parses it and shows the internal values
.../certs $ more nifi-cert.pem
@ -988,11 +1000,12 @@ Certificate:
e2:03:f0:af:68:c5:c1:12:88:3e:c4:f0:30:d5:28:18:7e:e0:
b3:e2:b9:4c:dc:17:51:6b:9e:33:df:ea:0e:95:cf:31:6f:37:
7b:c3:c4:37
```
----
==== nifi-key.key
```
[source]
----
# The first command shows the actual content of the encoded file, and the second parses it and shows the internal values
.../certs $ more nifi-key.key
@ -1114,7 +1127,7 @@ coefficient:
02:8c:5a:75:d2:f1:97:1f:4a:db:15:7f:7a:03:15:
f7:d7:61:1a:82:69:67:ae:86:93:26:83:d4:f0:75:
7a:00:bb:07:e9:13:91:82:9b
```
----
[[tls_external-signed_ca]]
==== Signing with Externally-signed CA Certificates
@ -1175,9 +1188,8 @@ $ ./bin/tls-toolkit.sh standalone -n 'node1.nifi.apache.org' \
* If the DER file only contains the public certificate, use this command:
** `openssl x509 -inform der -in cert.der -out cert.pem`
. To convert from a PKCS12 keystore (`keystore.p12`) containing both the public certificate and private key into PEM encoded files (`$PASSWORD` is the keystore password):
* `openssl pkcs12 -in keystore.p12 -out cert.der -nodes -password "pass:$PASSWORD"`
* `openssl pkcs12 -in keystore.p12 -nodes -clcerts -nokeys -out cert.pem -password "pass:$PASSWORD"`
* `openssl pkcs12 -in keystore.p12 -nodes -nocerts -out key.key -password "pass:$PASSWORD"`
* Follow the steps above to convert `cert.der` to `cert.pem`
. To convert from a Java Keystore (`keystore.jks`) containing private key into PEM encoded files (`$P12_PASSWORD` is the PKCS12 keystore password, `$JKS_PASSWORD` is the Java keystore password you want to set, and `$ALIAS` can be any value -- the NiFi default is `nifi-key`):
* `keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -srcstoretype JKS -deststoretype PKCS12 -destkeypass "$P12_PASSWORD" -deststorepass "$P12_PASSWORD" -srcstorepass "$JKS_PASSWORD" -srcalias "$ALIAS" -destalias "$ALIAS"`
* Follow the steps above to convert from `keystore.p12` to `cert.pem` and `key.key`