| <!DOCTYPE html> |
| <html> |
| <head> |
| <title>Apache BookKeeper™ - Encryption and Authentication using TLS</title> |
| |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| |
| <link rel="stylesheet" href="/css/normalize.css"> |
| <link rel="stylesheet" href="/css/tippy.css"> |
| <link rel="stylesheet" href="/css/style.css"> |
| |
| <link rel="shortcut icon" href="/img/favicon.ico"> |
| |
| <script src="/js/tippy.min.js"></script> |
| |
| <script type="text/javascript"> |
| var shiftWindow = function() { scrollBy(0, -25); }; |
| window.addEventListener("hashchange", shiftWindow); |
| window.addEventListener("pageshow", shiftWindow); |
| function load() { if (window.location.hash) shiftWindow(); } |
| </script> |
| </head> |
| <body class="body"> |
| <main class="main"> |
| |
| <nav class="navbar bk-topnav"> |
| <div class="navbar-brand"> |
| <a class="navbar-item bk-brand" href="/"> |
| Apache BookKeeper™ |
| </a> |
| |
| <div class="navbar-burger burger" data-target="bkNav"> |
| <span></span> |
| <span></span> |
| <span></span> |
| </div> |
| </div> |
| |
| <div id="bkNav" class="navbar-menu"> |
| <div class="navbar-start"> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link">Documentation</a> |
| <div class="navbar-dropdown is-boxed"> |
| <a class="navbar-item" href="/docs/latest/overview/overview"> |
| Version 4.15.0-SNAPSHOT |
| <span class="tag is-warning">Development</span> |
| </a> |
| <a class="navbar-item" href="/docs/latest/api/javadoc"> |
| <span class="icon bk-javadoc-icon"> |
| <img src="/img/java-icon.svg"> |
| </span> |
| Javadoc |
| </a> |
| <hr class="dropdown-divider"> |
| |
| <a class="navbar-item" href="/docs/4.14.0/overview/overview"> |
| Release 4.14.0 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.13.0/overview/overview"> |
| Release 4.13.0 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.12.1/overview/overview"> |
| Release 4.12.1 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.12.0/overview/overview"> |
| Release 4.12.0 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.11.1/overview/overview"> |
| Release 4.11.1 |
| |
| <span class="tag is-success">Stable</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.11.0/overview/overview"> |
| Release 4.11.0 |
| |
| </a> |
| |
| <a class="navbar-item" href="/docs/4.10.0/overview/overview"> |
| Release 4.10.0 |
| |
| </a> |
| |
| |
| <a class="navbar-item" href="/archives/docs/r4.9.2"> |
| Release 4.9.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.9.1"> |
| Release 4.9.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.9.0"> |
| Release 4.9.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.8.2"> |
| Release 4.8.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.8.1"> |
| Release 4.8.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.8.0"> |
| Release 4.8.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.7.3"> |
| Release 4.7.3 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.7.2"> |
| Release 4.7.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.7.1"> |
| Release 4.7.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.7.0"> |
| Release 4.7.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.6.2"> |
| Release 4.6.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.6.1"> |
| Release 4.6.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.6.0"> |
| Release 4.6.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.5.1"> |
| Release 4.5.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.5.0"> |
| Release 4.5.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.4.0"> |
| Release 4.4.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.3.2"> |
| Release 4.3.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.3.1"> |
| Release 4.3.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.3.0"> |
| Release 4.3.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.4"> |
| Release 4.2.4 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.3"> |
| Release 4.2.3 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.2"> |
| Release 4.2.2 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.1"> |
| Release 4.2.1 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.2.0"> |
| Release 4.2.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.1.0"> |
| Release 4.1.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| <a class="navbar-item" href="/archives/docs/r4.0.0"> |
| Release 4.0.0 |
| |
| <span class="tag is-warning">EOL</span> |
| |
| </a> |
| |
| </div> |
| </div> |
| |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link">Community</a> |
| <div class="navbar-dropdown is-boxed"> |
| <a class="navbar-item" href="/community/mailing-lists">Mailing lists</a> |
| <a class="navbar-item" href="/community/slack">Slack</a> |
| <a class="navbar-item" href="https://github.com/apache/bookkeeper/issues">Github Issues</a> |
| <a class="navbar-item" href="/community/releases">Release Management</a> |
| <a class="navbar-item" href="/community/meeting">Community Meetings</a> |
| <hr class="dropdown-divider"> |
| <a class="navbar-item" href="/community/contributing">Contribution Guide</a> |
| <a class="navbar-item" href="/community/coding_guide">Coding Guide</a> |
| <a class="navbar-item" href="/community/testing">Testing Guide</a> |
| <a class="navbar-item" href="/community/issue-report">Issue Report Guide</a> |
| <a class="navbar-item" href="/community/release_guide">Release Guide</a> |
| <hr class="dropdown-divider"> |
| <a class="navbar-item" href="/community/presentations">Presentations</a> |
| <a class="navbar-item" href="/community/bookkeeper_proposals">BookKeeper Proposals</a> |
| </div> |
| </div> |
| |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link">Project</a> |
| <div class="navbar-dropdown is-boxed"> |
| <a class="navbar-item" href="/project/who">Who are we?</a> |
| <a class="navbar-item" href="/project/bylaws">Bylaws</a> |
| <a class="navbar-item" href="http://www.apache.org/licenses/">License</a> |
| <hr class="dropdown-divider"> |
| <a class="navbar-item" href="/project/privacy">Privacy policy</a> |
| <a class="navbar-item" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="navbar-item" href="http://www.apache.org/foundation/thanks.html">Thanks</a> |
| </div> |
| </div> |
| </div> |
| |
| <div class="navbar-end"> |
| <div class="navbar-item"> |
| <div class="field is-grouped"> |
| <p class="control"> |
| <a class="button bk-twitter" href="https://twitter.com/asfbookkeeper"> |
| <span class="icon"> |
| <i class="fa fa-twitter"></i> |
| </span> |
| <span>Twitter</span> |
| </a> |
| </p> |
| <p class="control"> |
| <a class="button" href="https://github.com/apache/bookkeeper"> |
| <span class="icon"> |
| <i class="fa fa-github"></i> |
| </span> |
| <span>GitHub</span> |
| </a> |
| </p> |
| <p class="control"> |
| <a class="button is-primary" href="/releases"> |
| <span class="icon"> |
| <i class="fa fa-download"></i> |
| </span> |
| <span>Download</span> |
| </a> |
| </p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </nav> |
| |
| |
| <div class="bk-docs-container"> |
| <div class="columns is-gapless"> |
| <div class="column is-2 is-hidden-mobile"> |
| <div class="container"> |
| |
| <aside class="sidebar"> |
| |
| <a class="button is-info"> |
| Version: 4.8.2 |
| </a> |
| <hr /> |
| |
| <p> |
| Getting started |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../getting-started/installation"> |
| Installation |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../getting-started/run-locally"> |
| Run bookies locally |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../getting-started/concepts"> |
| Concepts and architecture |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Deployment |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../deployment/manual"> |
| Manual deployment |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../deployment/dcos"> |
| BookKeeper on DC/OS |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../deployment/kubernetes"> |
| BookKeeper on Kubernetes |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Administration |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../admin/bookies"> |
| BookKeeper administration |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/autorecovery"> |
| AutoRecovery |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/metrics"> |
| Metric collection |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/upgrade"> |
| Upgrade |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/http"> |
| BookKeeper Admin REST API |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../admin/decomission"> |
| Decommissioning Bookies |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| API |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../api/overview"> |
| Overview |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../api/ledger-api"> |
| Ledger API |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../api/ledger-adv-api"> |
| Advanced Ledger API |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../api/distributedlog-api"> |
| DistributedLog |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../api/javadoc"> |
| Java API Docs |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Security |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../security/overview"> |
| Overview |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../security/tls"> |
| TLS Authentication |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../security/sasl"> |
| SASL Authentication |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../security/zookeeper"> |
| ZooKeeper Authentication |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Development |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../development/protocol"> |
| BookKeeper protocol |
| </a> |
| </li> |
| |
| </ul> |
| |
| <p> |
| Reference |
| </p> |
| <ul class="sidebar-items"> |
| |
| |
| <li> |
| <a href="../../reference/config"> |
| Configuration |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../reference/cli"> |
| Command-line tools |
| </a> |
| </li> |
| |
| |
| <li> |
| <a href="../../reference/metrics"> |
| Metrics |
| </a> |
| </li> |
| |
| </ul> |
| |
| </aside> |
| |
| |
| </div> |
| </div> |
| |
| <div class="column is-8 bk-docs-block"> |
| <header class="docs-title"> |
| <nav class="level bk-level"> |
| <div class="level-left"> |
| <div class="level-item"> |
| <h1 class="title">Encryption and Authentication using TLS</h1> |
| </div> |
| </div> |
| |
| </nav> |
| |
| |
| </header> |
| |
| <hr /> |
| |
| <div class="content"> |
| <section class="bk-main-content"> |
| <p>Apache BookKeeper allows clients and autorecovery daemons to communicate over TLS, although this is not enabled by default.</p> |
| |
| <h2 id="overview">Overview</h2> |
| |
| <p>The bookies need their own key and certificate in order to use TLS. Clients can optionally provide a key and a certificate |
| for mutual authentication. Each bookie or client can also be configured with a truststore, which is used to |
| determine which certificates (bookie or client identities) to trust (authenticate).</p> |
| |
| <p>The truststore can be configured in many ways. To understand the truststore, consider the following two examples:</p> |
| |
| <ol> |
| <li>the truststore contains one or many certificates;</li> |
| <li>it contains a certificate authority (CA).</li> |
| </ol> |
| |
| <p>In (1), with a list of certificates, the bookie or client will trust any certificate listed in the truststore. |
| In (2), with a CA, the bookie or client will trust any certificate that was signed by the CA in the truststore.</p> |
| |
| <p>(TBD: benefits)</p> |
| |
| <h2 id="-generate-tls-key-and-certificate"><a name="bookie-keystore"></a> Generate TLS key and certificate</h2> |
| |
| <p>The first step of deploying TLS is to generate the key and the certificate for each machine in the cluster. |
| You can use Java’s <code class="highlighter-rouge">keytool</code> utility to accomplish this task. We will generate the key into a temporary keystore |
| initially so that we can export and sign it later with CA.</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>keytool <span class="nt">-keystore</span> bookie.keystore.jks <span class="nt">-alias</span> localhost <span class="nt">-validity</span> <span class="o">{</span>validity<span class="o">}</span> <span class="nt">-genkey</span> |
| </code></pre></div></div> |
| |
| <p>You need to specify two parameters in the above command:</p> |
| |
| <ol> |
| <li><code class="highlighter-rouge">keystore</code>: the keystore file that stores the certificate. The <em>keystore</em> file contains the private key of |
| the certificate; hence, it needs to be kept safely.</li> |
| <li><code class="highlighter-rouge">validity</code>: the valid time of the certificate in days.</li> |
| </ol> |
| |
| <div class="alert alert-success"> |
| Ensure that common name (CN) matches exactly with the fully qualified domain name (FQDN) of the server. |
| The client compares the CN with the DNS domain name to ensure that it is indeed connecting to the desired server, not a malicious one. |
| </div> |
| |
| <h2 id="creating-your-own-ca">Creating your own CA</h2> |
| |
| <p>After the first step, each machine in the cluster has a public-private key pair, and a certificate to identify the machine. |
| The certificate, however, is unsigned, which means that an attacker can create such a certificate to pretend to be any machine.</p> |
| |
| <p>Therefore, it is important to prevent forged certificates by signing them for each machine in the cluster. |
| A <code class="highlighter-rouge">certificate authority (CA)</code> is responsible for signing certificates. CA works likes a government that issues passports — |
| the government stamps (signs) each passport so that the passport becomes difficult to forge. Other governments verify the stamps |
| to ensure the passport is authentic. Similarly, the CA signs the certificates, and the cryptography guarantees that a signed |
| certificate is computationally difficult to forge. Thus, as long as the CA is a genuine and trusted authority, the clients have |
| high assurance that they are connecting to the authentic machines.</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>openssl req <span class="nt">-new</span> <span class="nt">-x509</span> <span class="nt">-keyout</span> ca-key <span class="nt">-out</span> ca-cert <span class="nt">-days</span> 365 |
| </code></pre></div></div> |
| |
| <p>The generated CA is simply a <em>public-private</em> key pair and certificate, and it is intended to sign other certificates.</p> |
| |
| <p>The next step is to add the generated CA to the clients’ truststore so that the clients can trust this CA:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>keytool <span class="nt">-keystore</span> bookie.truststore.jks <span class="nt">-alias</span> CARoot <span class="nt">-import</span> <span class="nt">-file</span> ca-cert |
| </code></pre></div></div> |
| |
| <p>NOTE: If you configure the bookies to require client authentication by setting <code class="highlighter-rouge">sslClientAuthentication</code> to <code class="highlighter-rouge">true</code> on the |
| <a href="../../reference/config">bookie config</a>, then you must also provide a truststore for the bookies and it should have all the CA |
| certificates that clients keys were signed by.</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>keytool <span class="nt">-keystore</span> client.truststore.jks <span class="nt">-alias</span> CARoot <span class="nt">-import</span> <span class="nt">-file</span> ca-cert |
| </code></pre></div></div> |
| |
| <p>In contrast to the keystore, which stores each machine’s own identity, the truststore of a client stores all the certificates |
| that the client should trust. Importing a certificate into one’s truststore also means trusting all certificates that are signed |
| by that certificate. As the analogy above, trusting the government (CA) also means trusting all passports (certificates) that |
| it has issued. This attribute is called the chain of trust, and it is particularly useful when deploying TLS on a large BookKeeper cluster. |
| You can sign all certificates in the cluster with a single CA, and have all machines share the same truststore that trusts the CA. |
| That way all machines can authenticate all other machines.</p> |
| |
| <h2 id="signing-the-certificate">Signing the certificate</h2> |
| |
| <p>The next step is to sign all certificates in the keystore with the CA we generated. First, you need to export the certificate from the keystore:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>keytool <span class="nt">-keystore</span> bookie.keystore.jks <span class="nt">-alias</span> localhost <span class="nt">-certreq</span> <span class="nt">-file</span> cert-file |
| </code></pre></div></div> |
| |
| <p>Then sign it with the CA:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>openssl x509 <span class="nt">-req</span> <span class="nt">-CA</span> ca-cert <span class="nt">-CAkey</span> ca-key <span class="nt">-in</span> cert-file <span class="nt">-out</span> cert-signed <span class="nt">-days</span> <span class="o">{</span>validity<span class="o">}</span> <span class="nt">-CAcreateserial</span> <span class="nt">-passin</span> pass:<span class="o">{</span>ca-password<span class="o">}</span> |
| </code></pre></div></div> |
| |
| <p>Finally, you need to import both the certificate of the CA and the signed certificate into the keystore:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>keytool <span class="nt">-keystore</span> bookie.keystore.jks <span class="nt">-alias</span> CARoot <span class="nt">-import</span> <span class="nt">-file</span> ca-cert |
| keytool <span class="nt">-keystore</span> bookie.keystore.jks <span class="nt">-alias</span> localhost <span class="nt">-import</span> <span class="nt">-file</span> cert-signed |
| </code></pre></div></div> |
| |
| <p>The definitions of the parameters are the following:</p> |
| |
| <ol> |
| <li><code class="highlighter-rouge">keystore</code>: the location of the keystore</li> |
| <li><code class="highlighter-rouge">ca-cert</code>: the certificate of the CA</li> |
| <li><code class="highlighter-rouge">ca-key</code>: the private key of the CA</li> |
| <li><code class="highlighter-rouge">ca-password</code>: the passphrase of the CA</li> |
| <li><code class="highlighter-rouge">cert-file</code>: the exported, unsigned certificate of the bookie</li> |
| <li><code class="highlighter-rouge">cert-signed</code>: the signed certificate of the bookie</li> |
| </ol> |
| |
| <p>(TBD: add a script to automatically generate truststores and keystores.)</p> |
| |
| <h2 id="configuring-bookies">Configuring Bookies</h2> |
| |
| <p>Bookies support TLS for connections on the same service port. In order to enable TLS, you need to configure <code class="highlighter-rouge">tlsProvider</code> to be either |
| <code class="highlighter-rouge">JDK</code> or <code class="highlighter-rouge">OpenSSL</code>. If <code class="highlighter-rouge">OpenSSL</code> is configured, it will use <code class="highlighter-rouge">netty-tcnative-boringssl-static</code>, which loads a corresponding binding according |
| to the platforms to run bookies.</p> |
| |
| <blockquote> |
| <p>Current <code class="highlighter-rouge">OpenSSL</code> implementation doesn’t depend on the system installed OpenSSL library. If you want to leverage the OpenSSL installed on |
| the system, you can check <a href="http://netty.io/wiki/forked-tomcat-native.html">this example</a> on how to replaces the JARs on the classpath with |
| netty bindings to leverage installed OpenSSL.</p> |
| </blockquote> |
| |
| <p>The following TLS configs are needed on the bookie side:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">tlsProvider</span><span class="o">=</span>OpenSSL |
| <span class="c"># key store</span> |
| <span class="nv">tlsKeyStoreType</span><span class="o">=</span>JKS |
| <span class="nv">tlsKeyStore</span><span class="o">=</span>/var/private/tls/bookie.keystore.jks |
| <span class="nv">tlsKeyStorePasswordPath</span><span class="o">=</span>/var/private/tls/bookie.keystore.passwd |
| <span class="c"># trust store</span> |
| <span class="nv">tlsTrustStoreType</span><span class="o">=</span>JKS |
| <span class="nv">tlsTrustStore</span><span class="o">=</span>/var/private/tls/bookie.truststore.jks |
| <span class="nv">tlsTrustStorePasswordPath</span><span class="o">=</span>/var/private/tls/bookie.truststore.passwd |
| </code></pre></div></div> |
| |
| <p>NOTE: it is important to restrict access to the store files and corresponding password files via filesystem permissions.</p> |
| |
| <p>Optional settings that are worth considering:</p> |
| |
| <ol> |
| <li>tlsClientAuthentication=false: Enable/Disable using TLS for authentication. This config when enabled will authenticate the other end |
| of the communication channel. It should be enabled on both bookies and clients for mutual TLS.</li> |
| <li>tlsEnabledCipherSuites= A cipher suite is a named combination of authentication, encryption, MAC and key exchange |
| algorithm used to negotiate the security settings for a network connection using TLS network protocol. By default, |
| it is null. <a href="https://www.openssl.org/docs/man1.0.2/apps/ciphers.html">OpenSSL Ciphers</a> |
| <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites">JDK Ciphers</a></li> |
| <li>tlsEnabledProtocols = TLSv1.2,TLSv1.1,TLSv1 (list out the TLS protocols that you are going to accept from clients). |
| By default, it is not set.</li> |
| </ol> |
| |
| <p>To verify the bookie’s keystore and truststore are setup correctly you can run the following command:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>openssl s_client <span class="nt">-debug</span> <span class="nt">-connect</span> localhost:3181 <span class="nt">-tls1</span> |
| </code></pre></div></div> |
| |
| <p>NOTE: TLSv1 should be listed under <code class="highlighter-rouge">tlsEnabledProtocols</code>.</p> |
| |
| <p>In the output of this command you should see the server’s certificate:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">-----BEGIN</span> CERTIFICATE----- |
| <span class="o">{</span>variable sized random bytes<span class="o">}</span> |
| <span class="nt">-----END</span> CERTIFICATE----- |
| </code></pre></div></div> |
| |
| <p>If the certificate does not show up or if there are any other error messages then your keystore is not setup correctly.</p> |
| |
| <h2 id="configuring-clients">Configuring Clients</h2> |
| |
| <p>TLS is supported only for the new BookKeeper client (BookKeeper versions 4.5.0 and higher), the older clients are not |
| supported. The configs for TLS will be the same as bookies.</p> |
| |
| <p>If client authentication is not required by the bookies, the following is a minimal configuration example:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">tlsProvider</span><span class="o">=</span>OpenSSL |
| <span class="nv">clientTrustStore</span><span class="o">=</span>/var/private/tls/client.truststore.jks |
| <span class="nv">clientTrustStorePasswordPath</span><span class="o">=</span>/var/private/tls/client.truststore.passwd |
| </code></pre></div></div> |
| |
| <p>If client authentication is required, then a keystore must be created for each client, and the bookies’ truststores must |
| trust the certificate in the client’s keystore. This may be done using commands that are similar to what we used for |
| the <a href="#bookie-keystore">bookie keystore</a>.</p> |
| |
| <p>And the following must also be configured:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">tlsClientAuthentication</span><span class="o">=</span><span class="nb">true |
| </span><span class="nv">clientKeyStore</span><span class="o">=</span>/var/private/tls/client.keystore.jks |
| <span class="nv">clientKeyStorePasswordPath</span><span class="o">=</span>/var/private/tls/client.keystore.passwd |
| </code></pre></div></div> |
| |
| <p>NOTE: it is important to restrict access to the store files and corresponding password files via filesystem permissions.</p> |
| |
| <p>(TBD: add example to use tls in bin/bookkeeper script?)</p> |
| |
| <h2 id="enabling-tls-logging">Enabling TLS Logging</h2> |
| |
| <p>You can enable TLS debug logging at the JVM level by starting the bookies and/or clients with <code class="highlighter-rouge">javax.net.debug</code> system property. For example:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">-Djavax</span>.net.debug<span class="o">=</span>all |
| </code></pre></div></div> |
| |
| <p>You can find more details on this in <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html">Oracle documentation</a> on |
| <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html">debugging SSL/TLS connections</a>.</p> |
| |
| </section> |
| |
| |
| <nav class="pagination is-centered"> |
| |
| <a class="pagination-previous" href="../overview">Previous</a> |
| |
| |
| <a class="pagination-next" href="../sasl">Next</a> |
| |
| <ul class="pagination-list"></ul> |
| </nav> |
| |
| </div> |
| </div> |
| |
| <div class="column is-2 is-hidden-mobile"> |
| |
| |
| <div class="toc"> |
| <h2 class="title">Encryption and Authentication using TLS</h2> |
| <ul class="section-nav"> |
| <li class="toc-entry toc-h2"><a href="#overview">Overview</a></li> |
| <li class="toc-entry toc-h2"><a href="#-generate-tls-key-and-certificate"> Generate TLS key and certificate</a></li> |
| <li class="toc-entry toc-h2"><a href="#creating-your-own-ca">Creating your own CA</a></li> |
| <li class="toc-entry toc-h2"><a href="#signing-the-certificate">Signing the certificate</a></li> |
| <li class="toc-entry toc-h2"><a href="#configuring-bookies">Configuring Bookies</a></li> |
| <li class="toc-entry toc-h2"><a href="#configuring-clients">Configuring Clients</a></li> |
| <li class="toc-entry toc-h2"><a href="#enabling-tls-logging">Enabling TLS Logging</a></li> |
| </ul> |
| </div> |
| |
| |
| |
| </div> |
| </div> |
| </div> |
| |
| |
| |
| <div id="entry-popover-html" class="popover-template"> |
| <p>An entry is a sequence of bytes (plus some metadata) written to a BookKeeper ledger. Entries are also known as records.</p> |
| |
| </div> |
| |
| <div id="ledger-popover-html" class="popover-template"> |
| <p>A ledger is a sequence of entries written to BookKeeper. Entries are written sequentially to ledgers and at most once, giving ledgers append-only semantics.</p> |
| |
| </div> |
| |
| <div id="bookie-popover-html" class="popover-template"> |
| <p>A bookie is an individual BookKeeper storage server.</p> |
| |
| <p>Bookies store the content of ledgers and act as a distributed ensemble.</p> |
| |
| </div> |
| |
| <div id="rereplication-popover-html" class="popover-template"> |
| <p>A subsystem that runs in the background on bookies to ensure that ledgers are fully replicated even if one bookie from the ensemble is down.</p> |
| |
| </div> |
| |
| <div id="striping-popover-html" class="popover-template"> |
| <p>Striping is the process of distributing BookKeeper ledgers to sub-groups of bookies rather than to all bookies in a BookKeeper ensemble.</p> |
| |
| <p>Striping is essential to ensuring fast performance.</p> |
| |
| </div> |
| |
| <div id="striped-popover-html" class="popover-template"> |
| <p>Striping is the process of distributing BookKeeper ledgers to sub-groups of bookies rather than to all bookies in a BookKeeper ensemble.</p> |
| |
| <p>Striping is essential to ensuring fast performance.</p> |
| |
| </div> |
| |
| <div id="journal-popover-html" class="popover-template"> |
| <p>A journal file stores BookKeeper transaction logs.</p> |
| |
| </div> |
| |
| <div id="fencing-popover-html" class="popover-template"> |
| <p>When a reader forces a ledger to close, preventing any further entries from being written to the ledger.</p> |
| |
| </div> |
| |
| <div id="record-popover-html" class="popover-template"> |
| <p>A record is a sequence of bytes (plus some metadata) written to a BookKeeper ledger. Records are also known as entries.</p> |
| |
| </div> |
| |
| |
| <script type="text/javascript"> |
| |
| tippy('#entry-popover', { |
| html: '#entry-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#ledger-popover', { |
| html: '#ledger-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#bookie-popover', { |
| html: '#bookie-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#rereplication-popover', { |
| html: '#rereplication-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#striping-popover', { |
| html: '#striping-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#striped-popover', { |
| html: '#striped-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#journal-popover', { |
| html: '#journal-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#fencing-popover', { |
| html: '#fencing-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| tippy('#record-popover', { |
| html: '#record-popover-html', |
| arrow: true, |
| animation: 'fade' |
| }); |
| |
| </script> |
| |
| </main> |
| |
| <footer class="footer"> |
| <div class="container"> |
| <div class="content has-text-centered"> |
| <p> |
| Copyright © 2016 - 2021 <a href="https://www.apache.org/">The Apache Software Foundation</a>,<br /> licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, version 2.0</a>. |
| </p> |
| <p> |
| Apache BookKeeper, BookKeeper®, Apache®, the Apache feature logo, and the Apache BookKeeper logo are either registered trademarks or trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| </div> |
| </footer> |
| |
| </body> |
| |
| <script src="/js/app.js"></script> |
| |
| |
| <!-- |
| 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. |
| --> |
| <script> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-104419626-1', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script> |
| |
| |
| </html> |