[pulsar] branch master updated: Documentation for TLS protocol version and ciphers (#3057)

[mm...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mmerli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git


The following commit(s) were added to refs/heads/master by this push:
     new ff76bd7  Documentation for TLS protocol version and ciphers (#3057)
ff76bd7 is described below

commit ff76bd7ee65dc78aab3745977070a88fd82a51ca
Author: Ivan Kelly <iv...@apache.org>
AuthorDate: Mon Nov 26 19:06:07 2018 +0100

    Documentation for TLS protocol version and ciphers (#3057)
    
    PR #1225 added the ability to configure the TLS protocol version and
    cipher on the server side, but this was never added to the
    documentation. This patch fixes that omission.
    
    Issue: #2402
---
 site2/docs/reference-configuration.md |  5 ++++-
 site2/docs/security-tls-transport.md  | 17 +++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/site2/docs/reference-configuration.md b/site2/docs/reference-configuration.md
index 08df5d1..0d23589 100644
--- a/site2/docs/reference-configuration.md
+++ b/site2/docs/reference-configuration.md
@@ -140,6 +140,8 @@ Pulsar brokers are responsible for handling incoming messages from producers, di
 |tlsKeyFilePath|  Path for the TLS private key file ||
 |tlsTrustCertsFilePath| Path for the trusted TLS certificate file ||
 |tlsAllowInsecureConnection|  Accept untrusted TLS certificate from client  |false|
+|tlsProtocols|Specify the tls protocols the broker will use to negotiate during TLS Handshake. Multiple values can be specified, separated by commas. Example:- ```TLSv1.2```, ```TLSv1.1```, ```TLSv1``` ||
+|tlsCiphers|Specify the tls cipher the broker will use to negotiate during TLS Handshake. Multiple values can be specified, separated by commas. Example:- ```TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256```||
 |maxUnackedMessagesPerConsumer| Max number of unacknowledged messages allowed to receive messages by a consumer on a shared subscription. Broker will stop sending messages to consumer once, this limit reaches until consumer starts acknowledging messages back. Using a value of 0, is disabling unackeMessage limit check and consumer can receive messages without any restriction  |50000|
 |maxUnackedMessagesPerSubscription| Max number of unacknowledged messages allowed per shared subscription. Broker will stop dispatching messages to all consumers of the subscription once this limit reaches until consumer starts acknowledging messages back and unack count reaches to limit/2. Using a value of 0, is disabling unackedMessage-limit check and dispatcher can dispatch messages without any restriction  |200000|
 |maxConcurrentLookupRequest|  Max number of concurrent lookup request broker allows to throttle heavy incoming lookup traffic |50000|
@@ -434,7 +436,8 @@ The [Pulsar proxy](concepts-architecture-overview.md#pulsar-proxy) can be config
 |tlsTrustCertsFilePath| Path for the trusted TLS certificate pem file ||
 |tlsHostnameVerificationEnabled|  Whether the hostname is validated when the proxy creates a TLS connection with brokers  |false|
 |tlsRequireTrustedClientCertOnConnect|  Whether client certificates are required for TLS. Connections are rejected if the client certificate isn’t trusted. |false|
-
+|tlsProtocols|Specify the tls protocols the broker will use to negotiate during TLS Handshake. Multiple values can be specified, separated by commas. Example:- ```TLSv1.2```, ```TLSv1.1```, ```TLSv1``` ||
+|tlsCiphers|Specify the tls cipher the broker will use to negotiate during TLS Handshake. Multiple values can be specified, separated by commas. Example:- ```TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256```||
 
 ## ZooKeeper
 
diff --git a/site2/docs/security-tls-transport.md b/site2/docs/security-tls-transport.md
index e521829..4faba02 100644
--- a/site2/docs/security-tls-transport.md
+++ b/site2/docs/security-tls-transport.md
@@ -125,6 +125,23 @@ tlsTrustCertsFilePath=/path/to/ca.cert.pem
 > A full list of parameters available in the `conf/broker.conf` file,
 > as well as the default values for those parameters, can be found in [Broker Configuration](reference-configuration.md#broker) 
 
+### TLS Protocol Version and Cipher
+
+The broker (and proxy) can be configured to require specific TLS protocol versions and ciphers for TLS negiotation. This can be used to stop clients from requesting downgraded TLS protocol versions or ciphers which may have weaknesses.
+
+Both the TLS protocol versions and cipher properties can take multiple values, separated by commas. The possible values for protocol version and ciphers depend on the TLS provider being used. Pulsar uses OpenSSL if available, but if not defaults back to the JDK implementation.
+
+```properties
+tlsProtocols=TLSv1.2,TLSv1.1
+tlsCiphers=TLS_DH_RSA_WITH_AES_256_GCM_SHA384,TLS_DH_RSA_WITH_AES_256_CBC_SHA
+```
+
+OpenSSL currently supports ```SSL2```, ```SSL3```, ```TLSv1```, ```TLSv1.1``` and ```TLSv1.2``` for the protocol version. A list of supported cipher can be acquired from the openssl ciphers command, i.e. ```openssl ciphers -tls_v2```.
+
+For JDK 8, a list of supported values can be obtained from the documentation:
+- [TLS protocol](https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#SSLContext)
+- [Ciphers](https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites)
+
 ## Proxy Configuration
 
 Proxies need to configure TLS in two directions, for clients connecting to the proxy, and for the proxy to be able to connect to brokers.