directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1005567 - in /websites/staging/directory/trunk/content: ./ api/user-guide/5.2-start-tls.html
Date Wed, 25 Jan 2017 12:56:43 GMT
Author: buildbot
Date: Wed Jan 25 12:56:43 2017
New Revision: 1005567

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 Wed Jan 25 12:56:43 2017
@@ -1 +1 @@
-1780171
+1780184

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 Wed Jan 25
12:56:43 2017
@@ -184,11 +184,11 @@
 }
 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="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>
+<p>As we have seen in the previous chapter, <strong>LDAPS</strong> has
some drawbacks. There is a better alternative when it comes to securing communication -- using
<strong>startTLS</strong>.</p>
+<p>The idea is to use an existing connection to send a message to the server and request
it to be encrypted. We keep going with the current connection, on the same port, but the exchanged
data will continue as encrypted.</p>
+<p>The <strong>startTLS</strong> extended operation is used for this. It's
a pure LDAP request that blocks other requests on the connection until it becomes 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>
+<p>It's quite simple. You just have to inform an opened connection to send the <strong>startTLS</strong>
extended operation.  It can be done at any time.  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>
@@ -202,8 +202,8 @@ h2:hover > .headerlink, h3:hover > .head
 </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>
+<p>As you can see, we'll used the <em>startTLS()</em> method, and it occurred
in the middle of an LDAP session.  (There previously was data transmission with the server
in clear text).</p>
+<p>You can also send the <em>startTLS</em> request prior to a bind, protecting
the entire 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>
@@ -215,10 +215,10 @@ h2:hover > .headerlink, h3:hover > .head
 </pre></div>
 
 
-<p>This is it...</p>
+<p>That's about 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>
+<p>We just saw 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 negotiation between the client and the server. It's not different from
the establishement of an <strong>LDAPS</strong> connection, except that we're
doing it on top of an existing <strong>LDAP</strong> connection. Still, the client
and the server must exchange ciphers, certificates, and agree on which protocol version to
use. You probably need more control.</p>
+<p>The <strong>startTLS()</strong> method uses an <strong>LdapConnectionConfig</strong>
instance for parameters in order to define things like -- <strong>TrustManagers</strong>,
allowed ciphers, enabled protocol versions, <strong>KeyManager</strong> instances,
etc. You simply need an <strong>LdapConnectionConfig</strong> instance, and load
it with instructions. for example, if you want to use a specific <strong>TrustManager</strong>
that doesn't verify the server's certificate:</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>
@@ -239,9 +239,9 @@ h2:hover > .headerlink, h3:hover > .head
 </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>
+<p>In this example, the <strong>startTls</strong> call uses the parameter
that was loaded into the <em>tlsConfig</em> instance.</p>
+<h2 id="heres-what-isnt-supported">Here's what isn't supported<a class="headerlink"
href="#heres-what-isnt-supported" title="Permanent link">&para;</a></h2>
+<p>The <a href="https://tools.ietf.org/html/rfc2830">LDAP StartTLS RFC</a>
requires more than securing connections. Typically, it's possible to stop securing a connection,
using a <strong>Graceful Closure</strong> operation. That feature isn't currently
supported.</p>
 
 
     <div class="nav">



Mime
View raw message