svn commit: r1005567 - in /websites/staging/directory/trunk/content: ./ api/user-guide/5.2-start-tls.html

[bu...@apache.org]

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">