This is an automated email from the ASF dual-hosted git repository.
alopresto pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nifi.git
The following commit(s) were added to refs/heads/master by this push:
new c5c2b30 NIFI-5926 Added certificate commands to toolkit guide.
Applied formatting and organizational changes from PR review.
c5c2b30 is described below
commit c5c2b308ed4653b79ec303977b811ef90a0c49c1
Author: Andy LoPresto <[email protected]>
AuthorDate: Thu Jan 3 16:36:28 2019 -0800
NIFI-5926 Added certificate commands to toolkit guide.
Applied formatting and organizational changes from PR review.
This closes #3242.
Signed-off-by: Andrew Lim <[email protected]>
---
.../src/main/asciidoc/administration-guide.adoc | 1 +
nifi-docs/src/main/asciidoc/toolkit-guide.adoc | 54 +++++++++++++---------
2 files changed, 32 insertions(+), 23 deletions(-)
diff --git a/nifi-docs/src/main/asciidoc/administration-guide.adoc
b/nifi-docs/src/main/asciidoc/administration-guide.adoc
index 61316f4..0244cfa 100644
--- a/nifi-docs/src/main/asciidoc/administration-guide.adoc
+++ b/nifi-docs/src/main/asciidoc/administration-guide.adoc
@@ -195,6 +195,7 @@ In order to facilitate the secure setup of NiFi, you can
use the `tls-toolkit` c
* <<toolkit-guide.adoc#wildcard_certificates,Wildcard Certificates>>
* <<toolkit-guide.adoc#tls_operation_modes,Operation Modes: Standalone and
Client/Server>>
* <<toolkit-guide.adoc#tls_intermediate_ca,Using An Existing Intermediate
Certificate Authority>>
+* <<toolkit-guide.adoc#additional_certificate_commands,Additional Certificate
Commands>>
[[user_authentication]]
diff --git a/nifi-docs/src/main/asciidoc/toolkit-guide.adoc
b/nifi-docs/src/main/asciidoc/toolkit-guide.adoc
index feda7cc..304f79c 100644
--- a/nifi-docs/src/main/asciidoc/toolkit-guide.adoc
+++ b/nifi-docs/src/main/asciidoc/toolkit-guide.adoc
@@ -727,7 +727,7 @@ Wildcard certificates (i.e. two nodes
`node1.nifi.apache.org` and `node2.nifi.ap
==== Potential issues with wildcard certificates
* In many places throughout the codebase, cluster communications use
certificate identities many times to identify a node, and if the certificate
simply presents a wildcard DN, that doesn’t resolve to a specific node
-* Admins may need to provide a custom node identity in _authorizers.xml_ for
`*.nifi.apache.org` because all proxy actions only resolve to the cert DN (see
the <<administration-guide.adoc#user_authentication,User Authentication>>
section in the System Administrator's Guide for more information).
+* Admins may need to provide a custom node identity in _authorizers.xml_ for
`*.nifi.apache.org` because all proxy actions only resolve to the cert DN (see
the <<administration-guide.adoc#user_authentication,User Authentication>>
section in the System Administrator's Guide for more information).
* Admins have no traceability into which node performed an action because they
all resolve to the same DN
* Admins running multiple instances on the same machine using different ports
to identify them can accidentally put `node1` hostname with `node2` port, and
the address will resolve fine because it’s using the same certificate, but the
host header handler will block it because the `node1` hostname is (correctly)
not listed as an acceptable host for `node2` instance
* If the wildcard certificate is compromised, all nodes are compromised
@@ -889,11 +889,9 @@ In some enterprise scenarios, a security/IT team may
provide a signing certifica
└── lib
```
-[[additional-commands]]
-==== Additional Commands
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
+==== nifi-cert.pem
```
# The first command shows the actual content of the encoded file, and the
second parses it and shows the internal values
@@ -985,7 +983,7 @@ Certificate:
7b:c3:c4:37
```
-===== nifi-key.key
+==== nifi-key.key
```
# The first command shows the actual content of the encoded file, and the
second parses it and shows the internal values
@@ -1111,27 +1109,11 @@ coefficient:
7a:00:bb:07:e9:13:91:82:9b
```
-. To convert from DER encoded public certificate (`cert.der`) to PEM encoded
(`cert.pem`):
- * If the DER file contains both the public certificate and private key,
remove the private key with this command:
- ** `perl -pe 'BEGIN{undef $/;} s|-----BEGIN PRIVATE KEY-----.*?-----END
PRIVATE KEY-----|Removed private key|gs' cert.der > cert.pem`
- * 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 -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`
-. To convert from PKCS #8 PEM format to PKCS #1 PEM format:
- * If the private key is provided in PKCS #8 format (the file begins with
`-----BEGIN PRIVATE KEY-----` rather than `-----BEGIN RSA PRIVATE KEY-----`),
the following command will convert it to PKCS #1 format, move the original to
`nifi-key-pkcs8.key`, and rename the PKCS #1 version as `nifi-key.key`:
- ** `openssl rsa -in nifi-key.key -out nifi-key-pkcs1.key && mv nifi-key.key
nifi-key-pkcs8.key && mv nifi-key-pkcs1.key nifi-key.key`
-
[[tls_external-signed_ca]]
==== Signing with Externally-signed CA Certificates
-To sign generated certificates with a certificate authority (CA) generated
outside of the TLS Toolkit, ensure the necessary files are in the right format
and location (see above). For example, an organization *Large Organization* has
an internal CA (`CN=ca.large.org, OU=Certificate Authority`). This *root CA* is
offline and only used to sign other internal CAs. The Large IT team generates
an *intermediate CA* (`CN=nifi_ca.large.org, OU=NiFi, OU=Certificate
Authority`) to be used to sign [...]
+To sign generated certificates with a certificate authority (CA) generated
outside of the TLS Toolkit, ensure the necessary files are in the right format
and location (see <<additional_certificate_commands>>). For example, an
organization *Large Organization* has an internal CA (`CN=ca.large.org,
OU=Certificate Authority`). This *root CA* is offline and only used to sign
other internal CAs. The Large IT team generates an *intermediate CA*
(`CN=nifi_ca.large.org, OU=NiFi, OU=Certificate A [...]
-To use the toolkit to generate these certificates and sign them using the
*intermediate CA*, ensure that the following files are present (see
<<additional-commands>> above):
+To use the toolkit to generate these certificates and sign them using the
*intermediate CA*, ensure that the following files are present (see
<<additional_certificate_commands>>):
* `nifi-cert.pem` -- the public certificate of the *intermediate CA* in PEM
format
* `nifi-key.key` -- the Base64-encoded private key of the *intermediate CA* in
PKCS #1 PEM format
@@ -1177,6 +1159,32 @@ $ ./bin/tls-toolkit.sh standalone -n
'node1.nifi.apache.org' \
2018/08/02 18:48:44 INFO [main]
org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: tls-toolkit
standalone completed successfully
----
+[[additional_certificate_commands]]
+=== Additional Certificate Commands
+
+. To convert from DER encoded public certificate (`cert.der`) to PEM encoded
(`cert.pem`):
+ * If the DER file contains both the public certificate and private key,
remove the private key with this command:
+ ** `perl -pe 'BEGIN{undef $/;} s|-----BEGIN PRIVATE KEY-----.*?-----END
PRIVATE KEY-----|Removed private key|gs' cert.der > cert.pem`
+ * 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 -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`
+. To convert from PKCS #8 PEM format to PKCS #1 PEM format:
+ * If the private key is provided in PKCS #8 format (the file begins with
`-----BEGIN PRIVATE KEY-----` rather than `-----BEGIN RSA PRIVATE KEY-----`),
the following command will convert it to PKCS #1 format, move the original to
`nifi-key-pkcs8.key`, and rename the PKCS #1 version as `nifi-key.key`:
+ ** `openssl rsa -in nifi-key.key -out nifi-key-pkcs1.key && mv nifi-key.key
nifi-key-pkcs8.key && mv nifi-key-pkcs1.key nifi-key.key`
+. To combine a private key in PEM format (`private.key`) and public
certificate in PEM format (`certificate.pem`) into PKCS12 keystore:
+ * The following command will create the PKCS12 keystore (`keystore.p12`)
from the two independent files. A Java keystore (JKS) cannot be formed directly
from the PEM files:
+ ** `openssl pkcs12 -export -out keystore.p12 -inkey private.key -in
certificate.pem`
+. To convert a PKCS12 keystore (`keystore.p12`) to JKS keystore
(`keystore.jks`):
+ * The following command will create the JKS keystore (`keystore.jks`). The
`-destalias` flag is optional, as NiFi does not currently read from a specific
alias in the keystore. The user will be prompted for a keystore password, which
must be set and have minimum 8 characters, and a key password, which can be the
same as the keystore password or different:
+ ** `keytool -importkeystore -srckeystore keystore.p12 -srcstoretype pkcs12
-destkeystore keystore.jks
+ -deststoretype jks -destalias nifi-key`
+
[[zookeeper_migrator]]
== ZooKeeper Migrator
You can use the `zk-migrator` tool to perform the following tasks:
