Repository: kafka Updated Branches: refs/heads/trunk 416817920 -> c89707f31
KAFKA-3667; Improve Section 7.2 Encryption and Authentication using SSL to include proper hostname verification configuration By default Kafka is configured to allow ssl communication without hostname verification. This docs has been amended to include instructions on how to set that up in the event clients would like to take a more conservative approach. Author: Ryan P <[email protected]> Reviewers: Ewen Cheslack-Postava <[email protected]>, Ismael Juma <[email protected]> Closes #1384 from rnpridgeon/KAFKA-3667 Project: http://git-wip-us.apache.org/repos/asf/kafka/repo Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/c89707f3 Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/c89707f3 Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/c89707f3 Branch: refs/heads/trunk Commit: c89707f315a6fe654b764840a49cdf5d9bbcfc90 Parents: 4168179 Author: Ryan P <[email protected]> Authored: Wed Aug 3 09:52:38 2016 +0100 Committer: Ismael Juma <[email protected]> Committed: Wed Aug 3 10:15:36 2016 +0100 ---------------------------------------------------------------------- docs/security.html | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/kafka/blob/c89707f3/docs/security.html ---------------------------------------------------------------------- diff --git a/docs/security.html b/docs/security.html index 7c96ddf..53d6cf1 100644 --- a/docs/security.html +++ b/docs/security.html @@ -45,8 +45,26 @@ Apache Kafka allows clients to connect over SSL. By default SSL is disabled but <li>keystore: the keystore file that stores the certificate. The keystore file contains the private key of the certificate; therefore, it needs to be kept safely.</li> <li>validity: the valid time of the certificate in days.</li> </ol> - Ensure that common name (CN) matches exactly with the fully qualified domain name (FQDN) of the server. The client compares the CN with the DNS domain name to ensure that it is indeed connecting to the desired server, not the malicious one.</li> - + <br> + Note: By default the property <code>ssl.endpoint.identification.algorithm</code> is not defined, so hostname verification is not performed. In order to enable hostname verification, set the following property: + + <pre> ssl.endpoint.identification.algorithm=HTTPS </pre> + + Once enabled, clients will verify the server's fully qualified domain name (FQDN) against one of the following two fields: + <ol> + <li>Common Name (CN) + <li>Subject Alternative Name (SAN) + </ol> + <br> + Both fields are valid, RFC-2818 recommends the use of SAN however. SAN is also more flexible, allowing for multiple DNS entries to be declared. Another advantage is that the CN can be set to a more meaningful value for authorization purposes. To add a SAN field append the following argument <code> -ext SAN=DNS:{FQDN} </code> to the keytool command: + <pre> + keytool -keystore server.keystore.jks -alias localhost -validity {validity} -genkey -ext SAN=DNS:{FQDN} + </pre> + The following command can be run afterwards to verify the contents of the generated certificate: + <pre> + keytool -list -v -keystore server.keystore.jks + </pre> + </li> <li><h4><a id="security_ssl_ca" href="#security_ssl_ca">Creating your own CA</a></h4> After the first step, each machine in the cluster has a public-private key pair, and a certificate to identify the machine. The certificate, however, is unsigned, which means that an attacker can create such a certificate to pretend to be any machine.<p> Therefore, it is important to prevent forged certificates by signing them for each machine in the cluster. A certificate authority (CA) is responsible for signing certificates. CA works likes a government that issues passportsâthe government stamps (signs) each passport so that the passport becomes difficult to forge. Other governments verify the stamps to ensure the passport is authentic. Similarly, the CA signs the certificates, and the cryptography guarantees that a signed certificate is computationally difficult to forge. Thus, as long as the CA is a genuine and trusted authority, the clients have high assurance that they are connecting to the authentic machines.
