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

NIFI-2477 Document TLS generation tool in Admin and Developer Guides 

Signed-off-by: Bryan Bende <bbende@apache.org>
This commit is contained in:
Andrew Lim 2016-08-12 14:44:38 -04:00 committed by Bryan Bende
parent 74661e6623
commit 9a16ca72d7
No known key found for this signature in database
GPG Key ID: A0DDA9ED50711C39
2 changed files with 104 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -169,6 +169,59 @@ Now that the User Interface has been secured, we can easily secure Site-to-Site
accomplished by setting the `nifi.remote.input.secure` and `nifi.cluster.protocol.is.secure` properties, respectively, to `true`.
TLS Generation Toolkit
~~~~~~~~~~~~~~~~~~~~~~
In order to facilitate the secure setup of NiFi, a tls-toolkit command line utility is available to automatically generate the required keystores, truststore, and relevant configuration files. This is especially useful for securing multiple NiFi nodes, which can be a tedious and error-prone process.
The tls-toolkit has two primary modes of operation:
1. Standalone -- generates the certificate authority, keystores, truststores, and nifi.properties files in one command.
2. Client/Server mode -- uses a Certificate Authority Server that accepts Certificate Signing Requests from clients, signs them, and sends the resulting certificates back. Both client and server validate the other’s identity through a shared secret.
Standalone
^^^^^^^^^^
Standalone mode can be invoked by running “tls-toolkit.sh standalone -h” which will print the usage information along with descriptions of options that can be specified.
The most common options to specify are:
* -n (or --hostnames) a comma-separated list of hostnames that you’d like to generate certificates for
* -f (or --nifiPropertiesFile) a base nifi.properties file that the tool will update for each host
* -o (or --outputDirectory) the directory to use for the resulting Certificate Authority files and NiFi configurations. A subdirectory will be made for each host.
* -p (or --httpsPort) the https port in nifi.properties and enable secure site-to-site. This is optional and not required if you’ve provided a template nifi.properties.
Client/Server
^^^^^^^^^^^^^
Client/Server mode relies on a long-running Certificate Authority (CA) to issue certificates. The CA can be stopped when you’re not bringing nodes online.
===== Server
The CA server can be invoked by running “tls-toolkit server -h” which will print the usage information.
The most common options to specify are:
* -f (or --configJson) the location of the json config (written after first run)
* -F (or --useConfigJson) load all relevant configuration from the config json (configJson is the only other argument necessary)
* -t (or --token) the token used to prevent man in the middle attacks (this should be a long, random value and needs to be known when invoking the client)
* -D (or --dn) the DN for the CA
===== Client
The client can be used to request new Certificates from the CA. The client utility will generate a keypair andCertificate Signing Request (CSR) and send the CSR to the Certificate Authority. The client can be invoked by running “tls-toolkit.sh client -h” which will print the usage information.
The most common options to specify are:
* -f (or --configJson) the json config file
* -c (or --certificateAuthorityHostname) the hostname of the CA
* -D (or --DN) the DN for the CSR (and Certificate)
* -t (or --token) the token used to prevent man in the middle attacks (this should be a long, random value and needs to be known when invoking the client)
* -T (or --keyStoreType) the type of keystore to create (specify jks for NiFi nodes, leave default to create client cert)
After running the client you will have the CA’s certificate, a keystore, a truststore, and a config.json with information about them as well as their passwords.
If you leave -T (or --keyStoreType) as its default value, PKCS12 will be used in order to make it easy to import into a browser for client certificates.
User Authentication
-------------------

18
nifi-docs/src/main/asciidoc/developer-guide.adoc
View File

@ -1907,8 +1907,25 @@ in many different ways to expose metrics and monitoring capabilities
needed for any number of operational concerns.
== Command Line Tools
=== tls-toolkit
The Client/Server mode of operation came about from the desire to automatically generate required TLS configuration artifacts without needing to perform that generation in a centralized place. This simplifies configuration in a clustered environment. Since we don’t necessarily have a central place to run the generation logic or a trusted Certificate Authority, a shared secret is used to authenticate the clients and server to each other.
The tls-toolkit prevents man in the middle attacks using HMAC verification of the public keys of the CA server and the CSR the client sends. A shared secret (the token) is used as the HMAC key.
The basic process goes as follows:
1. The client generates a KeyPair.
2. The client generates a request json payload containing a CSR and an HMAC with the token as the key and the CSR’s public key fingerprint as the data.
3. The client connects to the CA Hostname at the https port specified and validates that the CN of the CA’s certificate matches the hostname (NOTE: because we don’t trust the CA at this point, this adds NO security, it is just a way to error out early if possible).
4. The server validates the HMAC from the client payload using the token as the key and the CSR’s public key fingerprint as the data. This proves that the client knows the shared secret and that it wanted a CSR with that public key to be signed. (NOTE: a man in the middle could forward this on but wouldn’t be able to change the CSR without invalidating the HMAC, defeating the purpose).
5. The server signs the CSR and sends back a response json payload containing the certificate and an HMAC with the token as the key and a fingerprint of its public key as the data.
6. The client validates the response HMAC using the token as the key and a fingerprint of the certificate public key supplied by the TLS session. This validates that a CA that knows the shared secret is the one we are talking to over TLS.
7. The client verifies that the CA certificate from the TLS session signed the certificate in the payload.
8. The client adds the generated KeyPair to its keystore with the certificate chain and adds the CA certificate from the TLS connection to its truststore.
9. The client writes out the configuration json containing keystore, truststore passwords and other details about the exchange.
== Testing
@ -2294,4 +2311,3 @@ The developer mailing list (dev@nifi.apache.org) is monitored pretty closely, an
quickly. If you have a question, don't hesitate to shoot us an e-mail - we're here to help! Unfortunately, though, e-mails
can get lost in the shuffle, so if you do send an e-mail and don't get a response within a day or two, it's our fault - don't
worry about bothering us. Just ping the mailing list again.