blob: fdf94fa5af70af5183078ca03eaf2c68fa822803 [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<title>Apache BookKeeper&trade; - 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&trade;
</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.14.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.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.11.1
</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 &copy; 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>