directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1004866 - in /websites/staging/directory/trunk/content: ./ api/user-guide/5.2-start-tls.html
Date Sat, 14 Jan 2017 08:04:37 GMT
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">&para;</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">&para;</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">&para;</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> &quot;<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>&quot;
<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> &quot;<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>&quot;
<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">&para;</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> &quot;<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>&quot;<span
class="p">,</span> &quot;<span class="n">secret</span>&quot;
<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">&#39;</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">&para;</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>



Mime
View raw message