You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by bu...@apache.org on 2017/01/14 08:04:37 UTC
svn commit: r1004866 - in /websites/staging/directory/trunk/content: ./
api/user-guide/5.2-start-tls.html
Author: buildbot
Date: Sat Jan 14 08:04:36 2017
New Revision: 1004866
Log:
Staging update by buildbot for directory
Modified:
websites/staging/directory/trunk/content/ (props changed)
websites/staging/directory/trunk/content/api/user-guide/5.2-start-tls.html
Propchange: websites/staging/directory/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sat Jan 14 08:04:36 2017
@@ -1 +1 @@
-1777900
+1778724
Modified: websites/staging/directory/trunk/content/api/user-guide/5.2-start-tls.html
==============================================================================
--- websites/staging/directory/trunk/content/api/user-guide/5.2-start-tls.html (original)
+++ websites/staging/directory/trunk/content/api/user-guide/5.2-start-tls.html Sat Jan 14 08:04:36 2017
@@ -155,7 +155,7 @@
<div class="nav">
<div class="nav_prev">
- <a href="5.1-ssl.html">5.1 - SSL</a>
+ <a href="5.1-ldaps.html">5.1 - LDAPS</a>
</div>
<div class="nav_up">
@@ -165,7 +165,7 @@
</div>
<div class="nav_next">
- <a href="5.3-aci-and-acls.html">5.3 - ACI and ACLs</a>
+ <a href="5.3-sasl-bind.html">5.3 - SASL Bind</a>
</div>
<div class="clearfix"></div>
@@ -183,16 +183,71 @@
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
-<h1 id="53-starttls">5.3 - StartTLS<a class="headerlink" href="#53-starttls" title="Permanent link">¶</a></h1>
-<blockquote>
-<p><strong>Note:</strong> Contents for this page will be added soon...</p>
-</blockquote>
+<h1 id="52-starttls">5.2 - StartTLS<a class="headerlink" href="#52-starttls" title="Permanent link">¶</a></h1>
+<p>As we have seen in the previous chapter, <strong>LDAPS</strong> has some drawbacks. There is a better alterntive whne it comes to secure a communication : using <strong>startTLS</strong>.</p>
+<p>The whole idea is to use an existing connection to send a message to the server asking for a secured communication to be initiated. We keep going with the current connection, on the same port, but the exchanged data are now encrypted.</p>
+<p>The <strong>startTLS</strong> extended operation is used for that purpose. It's a pure LDAP request that will block any other requests done on the connection until it get secured. Of course, if some operations are pending, the operation will not be executed until the pending operations are completed.</p>
+<h2 id="how-to-use-it">How to use it<a class="headerlink" href="#how-to-use-it" title="Permanent link">¶</a></h2>
+<p>This is quite simple. You just have to tell an opened connection to sebd the <strong>startTLS</strong> extended operation, whenever you want. Here is a quick example :</p>
+<div class="codehilite"><pre><span class="k">try</span> <span class="p">(</span> <span class="n">LdapNetworkConnection</span> <span class="n">connection</span> <span class="p">=</span>
+ <span class="n">new</span> <span class="n">LdapNetworkConnection</span><span class="p">(</span> <span class="n">Network</span><span class="p">.</span><span class="n">LOOPBACK_HOSTNAME</span><span class="p">,</span> <span class="n">getLdapServer</span><span class="p">().</span><span class="n">getPort</span><span class="p">()</span> <span class="p">)</span> <span class="p">)</span>
+<span class="p">{</span>
+ <span class="n">connection</span><span class="p">.</span><span class="n">connect</span><span class="p">();</span>
+
+ <span class="n">Entry</span> <span class="n">admin</span> <span class="p">=</span> <span class="n">connection</span><span class="p">.</span><span class="n">lookup</span><span class="p">(</span> "<span class="n">uid</span><span class="p">=</span><span class="n">admin</span><span class="p">,</span><span class="n">ou</span><span class="p">=</span><span class="n">system</span>" <span class="p">);</span>
+
+ <span class="o">//</span> <span class="n">startTLS</span>
+ <span class="n">connection</span><span class="p">.</span><span class="n">startTls</span><span class="p">();</span>
+ <span class="p">...</span>
+</pre></div>
+
+
+<p>As you can see, we just use teh <em>startTLS()</em> method, and we did it in the middle of a LDAP session (we previously have requested some information from the server, that have been transmitted in clear text).</p>
+<p>You can also send the <em>startTLS</em> request before binding, protecting the whole session :</p>
+<div class="codehilite"><pre><span class="k">try</span> <span class="p">(</span> <span class="n">LdapNetworkConnection</span> <span class="n">connection</span> <span class="p">=</span>
+ <span class="n">new</span> <span class="n">LdapNetworkConnection</span><span class="p">(</span> <span class="n">Network</span><span class="p">.</span><span class="n">LOOPBACK_HOSTNAME</span><span class="p">,</span> <span class="n">getLdapServer</span><span class="p">().</span><span class="n">getPort</span><span class="p">()</span> <span class="p">)</span> <span class="p">)</span>
+<span class="p">{</span>
+ <span class="o">//</span> <span class="n">startTLS</span>
+ <span class="n">connection</span><span class="p">.</span><span class="n">startTls</span><span class="p">();</span>
+
+ <span class="n">Entry</span> <span class="n">admin</span> <span class="p">=</span> <span class="n">connection</span><span class="p">.</span><span class="n">lookup</span><span class="p">(</span> "<span class="n">uid</span><span class="p">=</span><span class="n">admin</span><span class="p">,</span><span class="n">ou</span><span class="p">=</span><span class="n">system</span>" <span class="p">);</span>
+ <span class="p">...</span>
+</pre></div>
+
+
+<p>This is it...</p>
+<h2 id="advanced-usage">Advanced usage<a class="headerlink" href="#advanced-usage" title="Permanent link">¶</a></h2>
+<p>What we just saw is the basic usage of the <strong>startTLS</strong> extended operation. Keep in mind that behind the scene, a <strong>TLS</strong> session will be established, which requires some negociation between the client and the server. It's not any different from the establishement of a <strong>LDAPS</strong> connection, except that we are doing so on top of an existing <strong>LDAP</strong> connection. Still, the client and the server are going to exchange ciphers, certificates, and agree on a protocol version to use. You probably need more control.</p>
+<p>The <strong>startTLS()</strong> method uses a <strong>LdapConnectionConfig</strong> instance for any parameter you would like to define (<strong>TrustManagers</strong>, list of allowed ciphers, enabled protocol versions, <strong>KeyManager</strong> instance, etc). You just need to get a <strong>LdapConnectionConfig</strong> instance, and feed it. for instance, if you want to use a specific <strong>TrustManager</strong> that does not check teh server's certiticate, just do :</p>
+<div class="codehilite"><pre><span class="n">LdapConnectionConfig</span> <span class="n">tlsConfig</span> <span class="p">=</span> <span class="n">new</span> <span class="n">LdapConnectionConfig</span><span class="p">();</span>
+<span class="n">tlsConfig</span><span class="p">.</span><span class="n">setLdapHost</span><span class="p">(</span> <span class="n">Network</span><span class="p">.</span><span class="n">LOOPBACK_HOSTNAME</span> <span class="p">);</span>
+<span class="n">tlsConfig</span><span class="p">.</span><span class="n">setLdapPort</span><span class="p">(</span> <span class="n">getLdapServer</span><span class="p">().</span><span class="n">getPort</span><span class="p">()</span> <span class="p">);</span>
+<span class="n">tlsConfig</span><span class="p">.</span><span class="n">setTrustManagers</span><span class="p">(</span> <span class="n">new</span> <span class="n">NoVerificationTrustManager</span><span class="p">()</span> <span class="p">);</span>
+
+<span class="k">try</span> <span class="p">(</span> <span class="n">LdapNetworkConnection</span> <span class="n">connection</span> <span class="p">=</span>
+ <span class="n">new</span> <span class="n">LdapNetworkConnection</span><span class="p">(</span> <span class="n">tlsConfig</span> <span class="p">)</span> <span class="p">)</span>
+<span class="p">{</span>
+ <span class="o">//</span> <span class="n">Connect</span>
+ <span class="n">connection</span><span class="p">.</span><span class="n">connect</span><span class="p">();</span>
+
+ <span class="o">//</span> <span class="n">At</span> <span class="n">this</span> <span class="n">point</span><span class="p">,</span> <span class="n">we</span> <span class="n">are</span> <span class="n">not</span> <span class="n">oo</span> <span class="n">a</span> <span class="n">secured</span> <span class="n">connection</span>
+ <span class="n">connection</span><span class="p">.</span><span class="n">bind</span><span class="p">(</span> "<span class="n">uid</span><span class="p">=</span><span class="n">admin</span><span class="p">,</span><span class="n">ou</span><span class="p">=</span><span class="n">system</span>"<span class="p">,</span> "<span class="n">secret</span>" <span class="p">);</span>
+
+ <span class="o">//</span> <span class="n">At</span> <span class="n">this</span> <span class="n">point</span><span class="p">,</span> <span class="n">we</span> <span class="n">are</span> <span class="n">not</span> <span class="n">oo</span> <span class="n">a</span> <span class="n">secured</span> <span class="n">connection</span><span class="p">.</span> <span class="n">Let</span><span class="o">'</span><span class="n">s</span> <span class="n">secure</span> <span class="n">it</span>
+ <span class="n">connection</span><span class="p">.</span><span class="n">startTls</span><span class="p">();</span>
+ <span class="p">...</span>
+</pre></div>
+
+
+<p>In this example, the <strong>startTls</strong> call will use whatever parameter that have been put in the <em>tlsConfig</em> instance.</p>
+<h2 id="what-we-dont-support">What we don't support<a class="headerlink" href="#what-we-dont-support" title="Permanent link">¶</a></h2>
+<p>The <a href="https://tools.ietf.org/html/rfc2830">LDAP StartTLS RFC</a> requires more than just securing the connection. Typically, it should be possible to stop securing the connection, using a <strong>Graceful Closure</strong>. We currently don't support this feature.</p>
<div class="nav">
<div class="nav_prev">
- <a href="5.1-ssl.html">5.1 - SSL</a>
+ <a href="5.1-ldaps.html">5.1 - LDAPS</a>
</div>
<div class="nav_up">
@@ -202,7 +257,7 @@ h2:hover > .headerlink, h3:hover > .head
</div>
<div class="nav_next">
- <a href="5.3-aci-and-acls.html">5.3 - ACI and ACLs</a>
+ <a href="5.3-sasl-bind.html">5.3 - SASL Bind</a>
</div>
<div class="clearfix"></div>