[
https://issues.apache.org/jira/browse/NIFI-2477?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15407114#comment-15407114
]
Bryan Rosander commented on NIFI-2477:
--------------------------------------
Rough draft:
Admin Guide:
The tls-toolkit has two primary modes of operation:
Standalone -- generates the certificate authority, keystores, truststores, and
nifi.properties files in one command.
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.
-R (or --sameKeyAndKeyStorePassword) use the same value when generating
KeyStore and TrustStore passwords which is currently needed
-p (or --httpsPort) the https port in nifi.properties and enable secure
site-to-site. This is optional and not necessary if you’ve provided a template
nifi.properties.
Client/Server:
Server:
Client/Server mode relies on a long-running CA (Certificate Authority) (that
can be stopped when you’re not bringing nodes online) to issue certificates.
The CA server can be invoked by running “tls-toolkit server -h” which will
print the usage information.
The most likely options to be specified 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
(if using, 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 and CSR (Certificate Signing Request) and send
the CSR to the certificate authority. The client can be invoked by running
“tls-toolkit.sh client -h” which will print usage information.
The most likely options to be specified 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).
Developer Guide:
This is a developer-oriented document, for the tls-toolkit. For the usage
information, please consult the Admin Guide.
The Client/Server mode of operation came about from the desire to be able to
autogenerate 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, using a shared
secret (the token) as the HMAC key.
The basic process goes as follows:
The client generates a KeyPair.
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.
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)
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. (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)
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.
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.
The client verifies that the CA certificate from the TLS session signed the
certificate in the payload.
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.
The client writes out the configuration json containing keystore, truststore
passwords and other details about the exchange.
> Document tls-toolkit
> --------------------
>
> Key: NIFI-2477
> URL: https://issues.apache.org/jira/browse/NIFI-2477
> Project: Apache NiFi
> Issue Type: Task
> Reporter: Bryan Rosander
>
> tls-toolkit created as part of NIFI-2193 needs to be documented in order to
> be a useful utility to ease the burden of configuring tls for one or more
> NiFi instances.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
