add docs

add new property for tcnative OCSP setting

Author: stoty

zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md

@@ -1776,6 +1776,16 @@ and [SASL authentication for ZooKeeper](https://cwiki.apache.org/confluence/disp
     Specifies whether Online Certificate Status Protocol is enabled in client and quorum TLS protocols.
     Default: false
 
+* *ssl.tcnative.ocsp* and *ssl.quorum.tcnative.ocsp* :
+    (Java system properties: **zookeeper.ssl.tcnative.ocsp** and **zookeeper.ssl.quorum.tcnative.ocsp**)
+    **New in 3.10.0:**
+    Specifies whether OCSP stapling is requested by the client.
+    This option has no effect unless the the OpenSSL tcnative SSL provider with the OpenSSL library is used.
+    Note that Zookeeper uses the the BoringSSL tcnative library by default, so even is the "OpenSSL" SSL provider is requested,
+    this won't do anything unless the default BoringSSL library is replaced with the OpenSSL one.
+    This options has no side effects on JVM global system properties.
+    Default: if the option is not set, or set to the value "default" then the library default is used.
+
 * *ssl.clientAuth* and *ssl.quorum.clientAuth* :
     (Java system properties: **zookeeper.ssl.clientAuth** and **zookeeper.ssl.quorum.clientAuth**)
     **Added in 3.5.5, but broken until 3.5.7:**

zookeeper-server/src/main/java/org/apache/zookeeper/common/ClientX509Util.java

@@ -19,6 +19,7 @@
 package org.apache.zookeeper.common;
 
 import io.netty.handler.ssl.DelegatingSslContext;
+import io.netty.handler.ssl.OpenSsl;
 import io.netty.handler.ssl.SslContext;
 import io.netty.handler.ssl.SslContextBuilder;
 import io.netty.handler.ssl.SslProvider;
@@ -82,7 +83,17 @@ public SslContext createNettySslContextForClient(ZKConfig config)
         SslProvider sslProvider = getSslProvider(config);
         sslContextBuilder.sslProvider(sslProvider);
         if (sslProvider == SslProvider.OPENSSL || sslProvider == SslProvider.OPENSSL_REFCNT) {
-            sslContextBuilder.enableOcsp(config.getBoolean(getSslOcspEnabledProperty()));
+            boolean ocspEnabled = config.getBoolean(getSslOcspEnabledProperty());
+            logTcnativeOcsp(ocspEnabled);
+            // Set it even in unsupported, tcnative will just ignore it
+            sslContextBuilder.enableOcsp(ocspEnabled);
+        }
+        // Explicit option takes precedence if set
+        if (config.getTristate(getSslTcnativeOcspEnabledProperty()).isTrue()) {
+            logTcnativeOcsp(true);
+            sslContextBuilder.enableOcsp(true);
+        } else if (config.getTristate(getSslTcnativeOcspEnabledProperty()).isFalse()) {
+            sslContextBuilder.enableOcsp(false);
         }
         String[] enabledProtocols = getEnabledProtocols(config);
         if (enabledProtocols != null) {
@@ -102,6 +113,14 @@ public SslContext createNettySslContextForClient(ZKConfig config)
         }
     }
 
+    private void logTcnativeOcsp(boolean enable) {
+        if (enable && !OpenSsl.isOcspSupported()) {
+            // SslContextBuilder.enableOcsp() doesn't do anything, unless the default BoringSSL
+            // tcnative dependency is replaced with an OpenSsl one.
+            LOG.warn("Trying to enable OCSP for tcnative OpenSSL provider, but it is not supported. The setting will be ignored");
+        }
+    }
+
     public SslContext createNettySslContextForServer(ZKConfig config)
         throws X509Exception.SSLContextException, X509Exception.KeyManagerException, X509Exception.TrustManagerException, SSLException {
         String keyStoreLocation = config.getProperty(getSslKeystoreLocationProperty(), "");
@@ -131,6 +150,11 @@ public SslContext createNettySslContextForServer(ZKConfig config, KeyManager key
         if (sslProvider == SslProvider.OPENSSL || sslProvider == SslProvider.OPENSSL_REFCNT) {
             sslContextBuilder.enableOcsp(config.getBoolean(getSslOcspEnabledProperty()));
         }
+        if (config.getTristate(getSslTcnativeOcspEnabledProperty()).isTrue()) {
+            sslContextBuilder.enableOcsp(true);
+        } else if (config.getTristate(getSslTcnativeOcspEnabledProperty()).isFalse()) {
+            sslContextBuilder.enableOcsp(false);
+        }
         String[] enabledProtocols = getEnabledProtocols(config);
         if (enabledProtocols != null) {
             sslContextBuilder.protocols(enabledProtocols);

zookeeper-server/src/main/java/org/apache/zookeeper/common/TriState.java

@@ -0,0 +1,53 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.zookeeper.common;
+
+/**
+ * For storing configuration parameters where want to distinguish a default case
+ * in addition to true and false.
+ */
+public enum TriState {
+    True, False, Default;
+
+    public static TriState parse(String value) {
+        if (value == null || value.equalsIgnoreCase("default")) {
+            return TriState.Default;
+        } else if (value.equalsIgnoreCase("true")) {
+            return TriState.True;
+        } else {
+            return TriState.False;
+        }
+    }
+
+    public boolean isTrue() {
+        return this == TriState.True;
+    }
+
+    public boolean isFalse() {
+        return this == TriState.False;
+    }
+
+    public boolean isDefault() {
+        return this == TriState.Default;
+    }
+
+    public boolean isNotDefault() {
+        return this != TriState.Default;
+    }
+}

zookeeper-server/src/main/java/org/apache/zookeeper/common/X509Util.java

@@ -164,6 +164,7 @@ public io.netty.handler.ssl.ClientAuth toNettyClientAuth() {
     private final String sslClientHostnameVerificationEnabledProperty = getConfigPrefix() + "clientHostnameVerification";
     private final String sslCrlEnabledProperty = getConfigPrefix() + "crl";
     private final String sslOcspEnabledProperty = getConfigPrefix() + "ocsp";
+    private final String sslTcnativeOcspEnabledProperty = getConfigPrefix() + ".tcnative.ocsp";
     private final String sslClientAuthProperty = getConfigPrefix() + "clientAuth";
     private final String sslHandshakeDetectionTimeoutMillisProperty = getConfigPrefix() + "handshakeDetectionTimeoutMillis";
 
@@ -248,6 +249,10 @@ public String getSslOcspEnabledProperty() {
         return sslOcspEnabledProperty;
     }
 
+    public String getSslTcnativeOcspEnabledProperty() {
+        return sslTcnativeOcspEnabledProperty;
+    }
+
     public String getSslClientAuthProperty() {
         return sslClientAuthProperty;
     }

zookeeper-server/src/main/java/org/apache/zookeeper/common/ZKConfig.java

@@ -131,6 +131,7 @@ private void putSSLProperties(X509Util x509Util) {
         properties.put(x509Util.getSslHostnameVerificationEnabledProperty(), System.getProperty(x509Util.getSslHostnameVerificationEnabledProperty()));
         properties.put(x509Util.getSslCrlEnabledProperty(), System.getProperty(x509Util.getSslCrlEnabledProperty()));
         properties.put(x509Util.getSslOcspEnabledProperty(), System.getProperty(x509Util.getSslOcspEnabledProperty()));
+        properties.put(x509Util.getSslTcnativeOcspEnabledProperty(), System.getProperty(x509Util.getSslTcnativeOcspEnabledProperty()));
         properties.put(x509Util.getSslClientAuthProperty(), System.getProperty(x509Util.getSslClientAuthProperty()));
         properties.put(x509Util.getSslHandshakeDetectionTimeoutMillisProperty(), System.getProperty(x509Util.getSslHandshakeDetectionTimeoutMillisProperty()));
         properties.put(x509Util.getFipsModeProperty(), System.getProperty(x509Util.getFipsModeProperty()));
@@ -284,4 +285,15 @@ public int getInt(String key, int defaultValue) {
         return defaultValue;
     }
 
+    /**
+     * Returns {@code TriState.True} if and only if the property named by the argument
+     * exists and is equal to the string {@code "true"}.
+     * Returns {@code TriState.Default} if and only if the property named by the argument
+     * does not exist or is equal to the string {@code "default"}.
+     * Returns {@code TriState.False} otherwise.
+     */
+    public TriState getTristate(String key) {
+        String propertyValue = getProperty(key);
+        return TriState.parse(propertyValue);
+    }
 }