directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From elecha...@apache.org
Subject svn commit: r1778724 - /directory/site/trunk/content/api/user-guide/5.2-start-tls.mdtext
Date Sat, 14 Jan 2017 08:04:25 GMT
Author: elecharny
Date: Sat Jan 14 08:04:25 2017
New Revision: 1778724

URL: http://svn.apache.org/viewvc?rev=1778724&view=rev
Log:
Added the content for startTLS

Modified:
    directory/site/trunk/content/api/user-guide/5.2-start-tls.mdtext

Modified: directory/site/trunk/content/api/user-guide/5.2-start-tls.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/5.2-start-tls.mdtext?rev=1778724&r1=1778723&r2=1778724&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/5.2-start-tls.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/5.2-start-tls.mdtext Sat Jan 14 08:04:25 2017
@@ -1,10 +1,10 @@
 Title: 5.2 - StartTLS
-NavPrev: 5.1-ssl.html
-NavPrevText: 5.1 - SSL
+NavPrev: 5.1-ldaps.html
+NavPrevText: 5.1 - LDAPS
 NavUp: 5-ldap-security.html
 NavUpText: 5 - LDAP Security
-NavNext: 5.3-aci-and-acls.html
-NavNextText: 5.3 - ACI and ACLs
+NavNext: 5.3-sasl-bind.html
+NavNextText: 5.3 - SASL Bind
 Notice: 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
@@ -22,6 +22,74 @@ Notice: Licensed to the Apache Software
     specific language governing permissions and limitations
     under the License.
 
-# 5.3 - StartTLS
+# 5.2 - StartTLS
+
+As we have seen in the previous chapter, **LDAPS** has some drawbacks. There is a better
alterntive whne it comes to secure a communication : using **startTLS**.
+
+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.
+
+The **startTLS** 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.
+
+## How to use it
+
+This is quite simple. You just have to tell an opened connection to sebd the **startTLS**
extended operation, whenever you want. Here is a quick example :
+
+    try ( LdapNetworkConnection connection = 
+       new LdapNetworkConnection( Network.LOOPBACK_HOSTNAME, getLdapServer().getPort() )
)
+    {
+        connection.connect();
+
+        Entry admin = connection.lookup( "uid=admin,ou=system" );
+
+        // startTLS
+        connection.startTls();
+        ...
+
+As you can see, we just use teh _startTLS()_ 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).
+
+You can also send the _startTLS_ request before binding, protecting the whole session :
+
+
+    try ( LdapNetworkConnection connection = 
+       new LdapNetworkConnection( Network.LOOPBACK_HOSTNAME, getLdapServer().getPort() )
)
+    {
+        // startTLS
+        connection.startTls();
+
+        Entry admin = connection.lookup( "uid=admin,ou=system" );
+        ...
+
+This is it...
+
+## Advanced usage
+
+What we just saw is the basic usage of the **startTLS** extended operation. Keep in mind
that behind the scene, a **TLS** session will be established, which requires some negociation
between the client and the server. It's not any different from the establishement of a **LDAPS**
connection, except that we are doing so on top of an existing **LDAP** 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.
+
+The **startTLS()** method uses a **LdapConnectionConfig** instance for any parameter you
would like to define (**TrustManagers**, list of allowed ciphers, enabled protocol versions,
**KeyManager** instance, etc). You just need to get a **LdapConnectionConfig** instance, and
feed it. for instance, if you want to use a specific **TrustManager** that does not check
teh server's certiticate, just do :
+
+    LdapConnectionConfig tlsConfig = new LdapConnectionConfig();
+    tlsConfig.setLdapHost( Network.LOOPBACK_HOSTNAME );
+    tlsConfig.setLdapPort( getLdapServer().getPort() );
+    tlsConfig.setTrustManagers( new NoVerificationTrustManager() );
+
+    try ( LdapNetworkConnection connection = 
+            new LdapNetworkConnection( tlsConfig ) )
+    {
+        // Connect
+        connection.connect();
+
+        // At this point, we are not oo a secured connection
+        connection.bind( "uid=admin,ou=system", "secret" );
+
+        // At this point, we are not oo a secured connection. Let's secure it
+        connection.startTls();
+        ...
+
+In this example, the **startTls** call will use whatever parameter that have been put in
the _tlsConfig_ instance.
+
+
+## What we don't support
+
+The [LDAP StartTLS RFC](https://tools.ietf.org/html/rfc2830) requires more than just securing
the connection. Typically, it should be possible to stop securing the connection, using a
**Graceful Closure**. We currently don't support this feature.
+
 
->**Note:** Contents for this page will be added soon...
\ No newline at end of file



Mime
View raw message