pulsar-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] sijie closed pull request #2794: Document TLS hostname verification option (#2403)
Date Wed, 17 Oct 2018 15:02:35 GMT
sijie closed pull request #2794: Document TLS hostname verification option (#2403)
URL: https://github.com/apache/pulsar/pull/2794
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/site2/docs/security-tls-transport.md b/site2/docs/security-tls-transport.md
index 9b29e76cd3..45ec390c3c 100644
--- a/site2/docs/security-tls-transport.md
+++ b/site2/docs/security-tls-transport.md
@@ -78,7 +78,8 @@ The following commands will ask you a few questions and then create the
certific
 > Sometimes it is not possible or makes no sense to match the hostname,
 > such as when the brokers are created with random hostnames, or you
 > plan to connect to the hosts via their IP. In this case, the client
-> should be configured to disable TLS hostname verification.
+> should be configured to disable TLS hostname verification. For more
+> details, see [the host verification section in client configuration](#hostname-verification).
 
 First generate the key.
 ```bash
@@ -146,6 +147,16 @@ When TLS transport encryption is enabled, you need to configure the client
to us
 
 As the server certificate you generated above doesn't belong to any of the default trust
chains, you also need to either specify the path the **trust cert** (recommended), or tell
the client to allow untrusted server certs.
 
+#### Hostname verification
+
+Hostname verification is a TLS security feature whereby a client can refuse to connect to
a server if the "CommonName" does not match the hostname to which it is connecting. By default,
Pulsar clients disable hostname verification, as it requires that each broker has a DNS record
and a unique cert.
+
+Moreover, as the administrator has full control of the certificate authority, it is unlikely
that a bad actor would be able to pull off a man-in-the-middle attack. "allowInsecureConnection"
allows the client to connect to servers whose cert has not been signed by an approved CA.
The client disables it by default, and should always be disabled in production environments.
As long as "allowInsecureConnection" is disabled, a man-in-the-middle attack would require
that the attacker has access to the CA.
+
+One scenario where you may want to enable hostname verification is where you have multiple
proxy nodes behind a VIP, and the VIP has a DNS record, for example, pulsar.mycompany.com.
In this case, you can generate a TLS cert with pulsar.mycompany.com as the "CommonName," and
then enable hostname verification on the client.
+
+The examples below show hostname verification being disabled for the Java client, though
you can be omit this as the client disables it by default. C++/python clients do now allow
this to be configured at the moment.
+
 ### CLI tools
 
 [Command-line tools](reference-cli-tools.md) like [`pulsar-admin`](reference-cli-tools#pulsar-admin),
[`pulsar-perf`](reference-cli-tools#pulsar-perf), and [`pulsar-client`](reference-cli-tools#pulsar-client)
use the `conf/client.conf` config file in a Pulsar installation.
@@ -158,6 +169,7 @@ brokerServiceUrl=pulsar+ssl://broker.example.com:6651/
 useTls=true
 tlsAllowInsecureConnection=false
 tlsTrustCertsFilePath=/path/to/ca.cert.pem
+tlsEnableHostnameVerification=false
 ```
 
 ### Java client
@@ -169,6 +181,8 @@ PulsarClient client = PulsarClient.builder()
     .serviceUrl("pulsar+ssl://broker.example.com:6651/")
     .enableTls(true)
     .tlsTrustCertsFilePath("/path/to/ca.cert.pem")
+    .enableTlsHostnameVerification(false) // false by default, in any case
+    .allowTlsInsecureConnection(false) // false by default, in any case
     .build();
 ```
 
@@ -179,7 +193,7 @@ from pulsar import Client
 
 client = Client("pulsar+ssl://broker.example.com:6651/",
                 tls_trust_certs_file_path="/path/to/ca.cert.pem",
-                tls_allow_insecure_connection=False)
+                tls_allow_insecure_connection=False) // defaults to false from v2.2.0 onwards
 ```
 
 ### C++ client
@@ -190,7 +204,7 @@ client = Client("pulsar+ssl://broker.example.com:6651/",
 pulsar::ClientConfiguration config;
 config.setUseTls(true);
 config.setTlsTrustCertsFilePath("/path/to/ca.cert.pem");
-config.setTlsAllowInsecureConnection(false);
+config.setTlsAllowInsecureConnection(false); // defaults to false from v2.2.0 onwards
 
 pulsar::Client client("pulsar+ssl://broker.example.com:6651/", config);
 ```


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

Mime
View raw message