docs/topics/impala_ssl.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
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.
-->
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="ssl">

  <title id="tls">Configuring TLS/SSL for Impala</title>

  <prolog>
    <metadata>
      <data name="Category" value="Impala"/>
      <data name="Category" value="Security"/>
      <data name="Category" value="SSL"/>
      <data name="Category" value="Encryption"/>
      <data name="Category" value="Configuring"/>
      <data name="Category" value="Administrators"/>
    </metadata>
  </prolog>

  <conbody>

    <p>
      <indexterm audience="hidden">SSL</indexterm>
      Impala supports TLS/SSL network encryption, between Impala and client
      programs, and between the Impala-related daemons running on different nodes
      in the cluster. This feature is important when you also use other features such as Kerberos
      authentication or Sentry authorization, where credentials are being
      transmitted back and forth.
    </p>

  </conbody>

  <concept id="concept_q1p_j2d_rp">

    <title>Using the Command Line</title>

    <conbody>
      <p>
        To enable SSL for when client applications connect to Impala, add both of the following flags to the <cmdname>impalad</cmdname> startup options:
      </p>

      <ul id="ul_i2p_m2d_rp">
        <li>
          <codeph>--ssl_server_certificate</codeph>: the full path to the server certificate, on the local filesystem.
        </li>

        <li>
          <codeph>--ssl_private_key</codeph>: the full path to the server private key, on the local filesystem.
        </li>
      </ul>

      <p rev="2.3.0">
        In <keyword keyref="impala23_full"/> and higher, Impala can also use SSL for its own internal communication between the
        <cmdname>impalad</cmdname>, <codeph>statestored</codeph>, and <codeph>catalogd</codeph> daemons.
        To enable this additional SSL encryption, set the <codeph>--ssl_server_certificate</codeph>
        and <codeph>--ssl_private_key</codeph> flags in the startup options for
        <cmdname>impalad</cmdname>, <cmdname>catalogd</cmdname>, and <cmdname>statestored</cmdname>,
        and also add the <codeph>--ssl_client_ca_certificate</codeph> flag for all three of those daemons.
      </p>

      <note conref="../shared/impala_common.xml#common/impala_kerberos_ssl_caveat"/>

      <p>
        If either of these flags are set, both must be set. In that case, Impala starts listening for Beeswax and HiveServer2 requests on
        SSL-secured ports only. (The port numbers stay the same; see <xref href="impala_ports.xml#ports"/> for details.)
      </p>

      <p>
        Since Impala uses passphrase-less certificates in PEM format, you can reuse a host's existing Java keystore
        by using the <codeph>openssl</codeph> toolkit to convert it to the PEM format.
      </p>

      <section id="secref">

        <title>Configuring TLS/SSL Communication for the Impala Shell</title>

        <p>
          With SSL enabled for Impala, use the following options when starting the
          <cmdname>impala-shell</cmdname> interpreter:
        </p>

        <ul id="ul_kgp_m2d_rp">
          <li>
            <codeph>--ssl</codeph>: enables TLS/SSL for <cmdname>impala-shell</cmdname>.
          </li>

          <li>
            <codeph>--ca_cert</codeph>: the local pathname pointing to the third-party CA certificate, or to a copy of the server
            certificate for self-signed server certificates.
          </li>
        </ul>

        <p>
          If <codeph>--ca_cert</codeph> is not set, <cmdname>impala-shell</cmdname> enables TLS/SSL, but does not validate the server
          certificate. This is useful for connecting to a known-good Impala that is only running over TLS/SSL, when a copy of the
          certificate is not available (such as when debugging customer installations).
        </p>

      </section>

    </conbody>

  </concept>

  <concept id="ssl_jdbc_odbc">
    <title>Using TLS/SSL with Business Intelligence Tools</title>
    <conbody>
      <p>
        You can use Kerberos authentication, TLS/SSL encryption, or both to secure
        connections from JDBC and ODBC applications to Impala.
        See <xref href="impala_jdbc.xml#impala_jdbc"/> and <xref href="impala_odbc.xml#impala_odbc"/>
        for details.
      </p>

      <p conref="../shared/impala_common.xml#common/hive_jdbc_ssl_kerberos_caveat"/>
    </conbody>
  </concept>

  <concept id="tls_min_version" rev="2.10.0 IMPALA-5743">

    <title>Specifying TLS/SSL Minimum Allowed Version and Ciphers</title>

    <conbody>

      <p>
        Depending on your cluster configuration and the security practices in your
        organization, you might need to restrict the allowed versions of TLS/SSL
        used by Impala. Older TLS/SSL versions might have vulnerabilities or lack
        certain features. In <keyword keyref="impala210_full"/>, you can use startup
        options for the <cmdname>impalad</cmdname>, <cmdname>catalogd</cmdname>,
        and <cmdname>statestored</cmdname> daemons to specify a minimum allowed
        version of TLS/SSL.
      </p>

      <p>
        Specify one of the following values for the <codeph>--ssl_minimum_version</codeph>
        configuration setting:
      </p>

      <ul>
        <li>
          <p>
            <codeph>tlsv1</codeph>: Allow any TLS version of 1.0 or higher.
            This setting is the default when TLS/SSL is enabled.
          </p>
        </li>
        <li>
          <p>
            <codeph>tlsv1.1</codeph>: Allow any TLS version of 1.1 or higher.
          </p>
        </li>
        <li>
          <p>
            <codeph>tlsv1.2</codeph>: Allow any TLS version of 1.2 or higher.
          </p>
        </li>
      </ul>

      <p>
        Along with specifying the version, you can also specify the allowed set of TLS ciphers
        by using the <codeph>--ssl_cipher_list</codeph> configuration setting. The argument to
        this option is a list of keywords, separated by colons, commas, or spaces, and
        optionally including other notation. For example:
      </p>

<codeblock>
--ssl_cipher_list="RC4-SHA,RC4-MD5"
</codeblock>

      <p>
        By default, the cipher list is empty, and Impala uses the default cipher list for
        the underlying platform. See the output of <cmdname>man ciphers</cmdname> for the full
        set of keywords and notation allowed in the argument string.
      </p>

    </conbody>

  </concept>

</concept>