X509Util (Apache ZooKeeper - Server 3.7.0 API)
Date: 2021-03-17

org.apache.zookeeper.common

## Class X509Util

- java.lang.Object
- - org.apache.zookeeper.common.X509Util

- All Implemented Interfaces:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    ClientX509Util, QuorumX509Util

      public abstract class X509Util
      extends Object
      implements Closeable, AutoCloseable

  Utility code for X509 handling Default cipher suites: Performance testing done by Facebook engineers shows that on Intel x86_64 machines, Java9 performs better with GCM and Java8 performs better with CBC, so these seem like reasonable defaults.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `X509Util.ClientAuth` Enum specifying the client auth requirement of server-side TLS sockets created by this X509Util.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_HANDSHAKE_DETECTION_TIMEOUT_MILLIS`
    `static String` | `DEFAULT_PROTOCOL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `X509Util()`
    `X509Util(ZKConfig zkConfig)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Disables automatic reloading of the trust store and key store files when they change on disk.
    `static X509KeyManager` | `createKeyManager(String keyStoreLocation, String keyStorePassword, String keyStoreTypeProp)` Creates a key manager by loading the key store from the given file of the given type, optionally decrypting it using the given password.
    `SSLContext` | `createSSLContext(ZKConfig config)`
    `SSLContextAndOptions` | `createSSLContextAndOptions(ZKConfig config)`
    `SSLContextAndOptions` | `createSSLContextAndOptionsFromConfig(ZKConfig config)`
    `SSLServerSocket` | `createSSLServerSocket()`
    `SSLServerSocket` | `createSSLServerSocket(int port)`
    `SSLSocket` | `createSSLSocket()`
    `SSLSocket` | `createSSLSocket(Socket socket, byte[] pushbackBytes)`
    `static X509TrustManager` | `createTrustManager(String trustStoreLocation, String trustStorePassword, String trustStoreTypeProp, boolean crlEnabled, boolean ocspEnabled, boolean serverHostnameVerificationEnabled, boolean clientHostnameVerificationEnabled)` Creates a trust manager by loading the trust store from the given file of the given type, optionally decrypting it using the given password.
    `void` | `enableCertFileReloading()` Enables automatic reloading of the trust store and key store files when they change on disk.
    `String` | `getCipherSuitesProperty()`
    `protected abstract String` | `getConfigPrefix()`
    `SSLContext` | `getDefaultSSLContext()`
    `SSLContextAndOptions` | `getDefaultSSLContextAndOptions()`
    `String` | `getSslCipherSuitesProperty()`
    `String` | `getSslClientAuthProperty()`
    `String` | `getSslContextSupplierClassProperty()`
    `String` | `getSslCrlEnabledProperty()`
    `String` | `getSslEnabledProtocolsProperty()`
    `String` | `getSslHandshakeDetectionTimeoutMillisProperty()` Returns the config property key that controls the amount of time, in milliseconds, that the first UnifiedServerSocket read operation will block for when trying to detect the client mode (TLS or PLAINTEXT).
    `int` | `getSslHandshakeTimeoutMillis()` Returns the max amount of time, in milliseconds, that the first UnifiedServerSocket read() operation should block for when trying to detect the client mode (TLS or PLAINTEXT).
    `String` | `getSslHostnameVerificationEnabledProperty()`
    `String` | `getSslKeystoreLocationProperty()`
    `String` | `getSslKeystorePasswdProperty()`
    `String` | `getSslKeystoreTypeProperty()`
    `String` | `getSslOcspEnabledProperty()`
    `String` | `getSslProtocolProperty()`
    `String` | `getSslTruststoreLocationProperty()`
    `String` | `getSslTruststorePasswdProperty()`
    `String` | `getSslTruststoreTypeProperty()`
    `static KeyStore` | `loadKeyStore(String keyStoreLocation, String keyStorePassword, String keyStoreTypeProp)`
    `static KeyStore` | `loadTrustStore(String trustStoreLocation, String trustStorePassword, String trustStoreTypeProp)`
    `protected abstract boolean` | `shouldVerifyClientHostname()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_PROTOCOL

          public static final String DEFAULT_PROTOCOL

      See Also:
        Constant Field Values

    - #### DEFAULT_HANDSHAKE_DETECTION_TIMEOUT_MILLIS

          public static final int DEFAULT_HANDSHAKE_DETECTION_TIMEOUT_MILLIS

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### X509Util

          public X509Util()

    - #### X509Util

          public X509Util(ZKConfig zkConfig)

  - ### Method Detail

    - #### getConfigPrefix

          protected abstract String getConfigPrefix()

    - #### shouldVerifyClientHostname

          protected abstract boolean shouldVerifyClientHostname()

    - #### getSslProtocolProperty

          public String getSslProtocolProperty()

    - #### getSslEnabledProtocolsProperty

          public String getSslEnabledProtocolsProperty()

    - #### getCipherSuitesProperty

          public String getCipherSuitesProperty()

    - #### getSslKeystoreLocationProperty

          public String getSslKeystoreLocationProperty()

    - #### getSslCipherSuitesProperty

          public String getSslCipherSuitesProperty()

    - #### getSslKeystorePasswdProperty

          public String getSslKeystorePasswdProperty()

    - #### getSslKeystoreTypeProperty

          public String getSslKeystoreTypeProperty()

    - #### getSslTruststoreLocationProperty

          public String getSslTruststoreLocationProperty()

    - #### getSslTruststorePasswdProperty

          public String getSslTruststorePasswdProperty()

    - #### getSslTruststoreTypeProperty

          public String getSslTruststoreTypeProperty()

    - #### getSslContextSupplierClassProperty

          public String getSslContextSupplierClassProperty()

    - #### getSslHostnameVerificationEnabledProperty

          public String getSslHostnameVerificationEnabledProperty()

    - #### getSslCrlEnabledProperty

          public String getSslCrlEnabledProperty()

    - #### getSslOcspEnabledProperty

          public String getSslOcspEnabledProperty()

    - #### getSslClientAuthProperty

          public String getSslClientAuthProperty()

    - #### getSslHandshakeDetectionTimeoutMillisProperty

          public String getSslHandshakeDetectionTimeoutMillisProperty()

      Returns the config property key that controls the amount of time, in milliseconds, that the first UnifiedServerSocket read operation will block for when trying to detect the client mode (TLS or PLAINTEXT).
      Returns:
        the config property key.

    - #### getDefaultSSLContext

          public SSLContext getDefaultSSLContext()
                                          throws X509Exception.SSLContextException

      Throws:
        `X509Exception.SSLContextException`

    - #### createSSLContext

          public SSLContext createSSLContext(ZKConfig config)
                                      throws X509Exception.SSLContextException

      Throws:
        `X509Exception.SSLContextException`

    - #### getDefaultSSLContextAndOptions

          public SSLContextAndOptions getDefaultSSLContextAndOptions()
                                                              throws X509Exception.SSLContextException

      Throws:
        `X509Exception.SSLContextException`

    - #### getSslHandshakeTimeoutMillis

          public int getSslHandshakeTimeoutMillis()

      Returns the max amount of time, in milliseconds, that the first UnifiedServerSocket read() operation should block for when trying to detect the client mode (TLS or PLAINTEXT). Defaults to `DEFAULT_HANDSHAKE_DETECTION_TIMEOUT_MILLIS`.
      Returns:
        the handshake detection timeout, in milliseconds.

    - #### createSSLContextAndOptions

          public SSLContextAndOptions createSSLContextAndOptions(ZKConfig config)
                                                          throws X509Exception.SSLContextException

      Throws:
        `X509Exception.SSLContextException`

    - #### createSSLContextAndOptionsFromConfig

          public SSLContextAndOptions createSSLContextAndOptionsFromConfig(ZKConfig config)
                                                                    throws X509Exception.SSLContextException

      Throws:
        `X509Exception.SSLContextException`

    - #### loadKeyStore

          public static KeyStore loadKeyStore(String keyStoreLocation,
                                              String keyStorePassword,
                                              String keyStoreTypeProp)
                                       throws IOException,
                                              GeneralSecurityException

      Throws:
        `IOException`
        `GeneralSecurityException`

    - #### loadTrustStore

          public static KeyStore loadTrustStore(String trustStoreLocation,
                                                String trustStorePassword,
                                                String trustStoreTypeProp)
                                         throws IOException,
                                                GeneralSecurityException

      Throws:
        `IOException`
        `GeneralSecurityException`

    - #### createKeyManager

          public static X509KeyManager createKeyManager(String keyStoreLocation,
                                                        String keyStorePassword,
                                                        String keyStoreTypeProp)
                                                 throws X509Exception.KeyManagerException

      Creates a key manager by loading the key store from the given file of the given type, optionally decrypting it using the given password.
      Parameters:
        `keyStoreLocation` - the location of the key store file.
        `keyStorePassword` - optional password to decrypt the key store. If empty, assumes the key store is not encrypted.
        `keyStoreTypeProp` - must be JKS, PEM, PKCS12, BCFKS or null. If null, attempts to autodetect the key store type from the file extension (e.g. .jks / .pem).
      Returns:
        the key manager.
      Throws:
        `X509Exception.KeyManagerException` - if something goes wrong.

    - #### createTrustManager

          public static X509TrustManager createTrustManager(String trustStoreLocation,
                                                            String trustStorePassword,
                                                            String trustStoreTypeProp,
                                                            boolean crlEnabled,
                                                            boolean ocspEnabled,
                                                            boolean serverHostnameVerificationEnabled,
                                                            boolean clientHostnameVerificationEnabled)
                                                     throws X509Exception.TrustManagerException

      Creates a trust manager by loading the trust store from the given file of the given type, optionally decrypting it using the given password.
      Parameters:
        `trustStoreLocation` - the location of the trust store file.
        `trustStorePassword` - optional password to decrypt the trust store (only applies to JKS trust stores). If empty, assumes the trust store is not encrypted.
        `trustStoreTypeProp` - must be JKS, PEM, PKCS12, BCFKS or null. If null, attempts to autodetect the trust store type from the file extension (e.g. .jks / .pem).
        `crlEnabled` - enable CRL (certificate revocation list) checks.
        `ocspEnabled` - enable OCSP (online certificate status protocol) checks.
        `serverHostnameVerificationEnabled` - if true, verify hostnames of remote servers that client sockets created by this X509Util connect to.
        `clientHostnameVerificationEnabled` - if true, verify hostnames of remote clients that server sockets created by this X509Util accept connections from.
      Returns:
        the trust manager.
      Throws:
        `X509Exception.TrustManagerException` - if something goes wrong.

    - #### createSSLSocket

          public SSLSocket createSSLSocket()
                                    throws X509Exception,
                                           IOException

      Throws:
        `X509Exception`
        `IOException`

    - #### createSSLSocket

          public SSLSocket createSSLSocket(Socket socket,
                                           byte[] pushbackBytes)
                                    throws X509Exception,
                                           IOException

      Throws:
        `X509Exception`
        `IOException`

    - #### createSSLServerSocket

          public SSLServerSocket createSSLServerSocket()
                                                throws X509Exception,
                                                       IOException

      Throws:
        `X509Exception`
        `IOException`

    - #### createSSLServerSocket

          public SSLServerSocket createSSLServerSocket(int port)
                                                throws X509Exception,
                                                       IOException

      Throws:
        `X509Exception`
        `IOException`

    - #### enableCertFileReloading

          public void enableCertFileReloading()
                                       throws IOException

      Enables automatic reloading of the trust store and key store files when they change on disk.
      Throws:
        `IOException` - if creating the FileChangeWatcher objects fails.

    - #### close

          public void close()

      Disables automatic reloading of the trust store and key store files when they change on disk. Stops background threads and closes WatchService instances.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`

Copyright © 2008–2021 The Apache Software Foundation. All rights reserved.